Rails Blocks CLI
The Rails Blocks CLI installs components directly into your Rails app. Free components are read from the public Rails Blocks component registry, while Pro components use your Rails Blocks account token.
Before using the CLI to install components, complete the Installation guide once for your app. That setup covers Rails Blocks dependencies, Stimulus loading, and custom CSS.
Install the CLI
Install the Ruby gem once, then run commands from the root of your Rails application.
gem install rails-blocks-cliFind components
Browse the public registry, search for a component, or inspect its metadata before installing anything.
# List every component in the registry
rails-blocks list
# List only free components
rails-blocks list --free
# Search components by name
rails-blocks search dropdown
# Inspect a component's metadata before installing
rails-blocks show accordionInstall components
Start with a dry run to preview the files that will be written. If you do not pass --as, the CLI asks which format to install in an interactive terminal and defaults to ERB partials in non-interactive contexts.
# Preview the files before writing anything
rails-blocks install accordion --dry-run
# Install a single component as ERB partials
rails-blocks install accordion --as erb_template
# Install a single component as ViewComponent files
rails-blocks install accordion --as view_component
# Override the component destination
rails-blocks install accordion --as erb_template --path app/views/components
# Override where required Stimulus controllers are written
rails-blocks install accordion --stimulus-path app/frontend/controllers
# Preview every free component as shared partials
rails-blocks install --all --free --as partial --dry-run
# Install every available component as ViewComponent files
rails-blocks install --all --as view_componentDefault install paths
- ERB partials:
app/views/shared/<component>/ - ViewComponents:
app/components/<component>/ - Stimulus controllers:
app/javascript/controllers/
Required Stimulus controllers are installed automatically when missing. Existing files are skipped unless you pass --force.
Update components
Use diff to review local changes against the latest Rails Blocks package, then use update to write changed files. Updates do not require --force; reserve --force for install-time overwrites.
# Compare your local shared partials with the latest accordion package
rails-blocks diff accordion --as partial
# Update the accordion shared partials after reviewing the diff
rails-blocks update accordion --as partial
# Preview updates for every free ViewComponent package
rails-blocks update --all --free --as view_component --dry-run
# Update every available shared partial package
rails-blocks update --all --as partialUpdate Stimulus controllers
Stimulus controller updates write to app/javascript/controllers. Free controllers can be fetched anonymously; Pro controller updates use your Rails Blocks token.
# Compare one local Stimulus controller with the latest free controller
rails-blocks diff stimulus tooltip
# Update one Stimulus controller
rails-blocks update stimulus tooltip
# Compare all free Stimulus controllers
rails-blocks diff stimulus --all --free
# Update all Pro-access Stimulus controllers after logging in
rails-blocks update stimulus --all --proUse Pro components
Pro components require an access token so the CLI can fetch Pro docs and packages without using your password or browser session. The CLI can open a browser approval flow, or send a magic-code approval email when browser handoff is not convenient.
# Start the browser-based CLI login flow
rails-blocks login
# Start login with an email magic-code fallback
rails-blocks login --email you@example.com
# Verify which API token the CLI is using
rails-blocks whoami
# Preview a Pro component install before writing files
rails-blocks install dropdown --dry-run
# Install a Pro component
rails-blocks install dropdown
# Install every Pro component as ViewComponent files
rails-blocks install --all --pro --as view_componentUseful commands
rails-blocks doctor- Check registry, API, and token configuration.
rails-blocks docs tooltip- Read component docs or get canonical web and markdown links.
rails-blocks examples modal- Print usage examples for a component.
rails-blocks logout- Remove the local Rails Blocks API token.
Use the CLI as an AI skill
If you want a simpler setup than MCP, install this skill in your AI coding agent so it knows how to use the Rails Blocks CLI directly from your Rails app.
npx skills add Rails-Blocks/components --skill rails-blocks-cli
If your agent does not support npx skills yet, copy the skill manually.
---
name: rails-blocks-cli
description: Use this skill when the user wants an AI agent to add, update, inspect, preview, or read docs for Rails Blocks UI components in a Rails app using the rails-blocks CLI instead of MCP. Trigger for requests like "install the accordion component", "add Rails Blocks dropdown", "update Rails Blocks Stimulus controllers", "preview Rails Blocks files", or "use Rails Blocks Pro components". Do not use for general Rails UI work unrelated to Rails Blocks.
---
# Rails Blocks CLI
Use the `rails-blocks` CLI to discover, preview, install, and update Rails Blocks components in a Rails app.
Default to ERB partials unless the app already uses ViewComponent.
## Requirements
- Ruby 3.2 or newer.
- The command is available after `gem install rails-blocks-cli`.
- Run commands from the target Rails app root.
## Workflow
1. Confirm the command is being run from the Rails app root.
2. Check the CLI with `rails-blocks doctor`. If the command is missing, install it with `gem install rails-blocks-cli`.
3. Discover components with `rails-blocks list`, `rails-blocks list --free`, or `rails-blocks search QUERY`.
4. Read docs before installing with `rails-blocks docs COMPONENT`; inspect examples with `rails-blocks examples COMPONENT` when useful.
5. Preview file writes before changing the app: `rails-blocks install COMPONENT --dry-run`.
6. Summarize the files the dry run would write and ask before making changes.
7. Install with `rails-blocks install COMPONENT --as erb_template` unless ViewComponent is the better fit.
8. Use custom paths instead of moving files after install: `--path app/views/components` and `--stimulus-path app/javascript/controllers`.
9. After installation, inspect `git diff` and report the changed files.
## Updates
1. Review changes first with `rails-blocks diff COMPONENT --as erb_template` or `rails-blocks diff stimulus NAME`.
2. Apply updates only after review with `rails-blocks update COMPONENT --as erb_template` or `rails-blocks update stimulus NAME`.
3. Inspect `git diff` after updating.
## Rules
- Use `--dry-run` before installs or updates unless the user explicitly approves writing files.
- Do not pass `--force` unless the user explicitly approves overwriting existing files.
- If the user asks for all free components, use `rails-blocks install --all --free --dry-run` first.
- If the user asks for Pro components, run `rails-blocks login` first or ask them to provide `RAILS_BLOCKS_API_TOKEN`.
- If styling, JavaScript behavior, or dependency issues appear, tell the user to complete the Rails Blocks installation guide before retrying component installs.
- Prefer the app's existing component style. Use ViewComponent when the app already uses ViewComponent; otherwise use ERB partials.
## Gotchas
- Free components do not require a Rails Blocks account.
- Pro components require a Pro token.
- Required Stimulus controllers are installed automatically when missing.
- Existing files are skipped unless `--force` is passed.
- Run commands from the target Rails app root, not from a gem or engine subdirectory.
## Common Commands
```bash
rails-blocks list --free
rails-blocks search dropdown
rails-blocks docs accordion
rails-blocks install accordion --dry-run
rails-blocks install accordion --as erb_template
rails-blocks install accordion --as view_component
rails-blocks diff accordion --as erb_template
rails-blocks update accordion --as erb_template
rails-blocks diff stimulus tooltip
rails-blocks update stimulus tooltip
rails-blocks login
rails-blocks doctor
```