# Rails Blocks CLI

Install Rails Blocks components from your terminal into a Rails application.

The CLI reads free components from the public Rails Blocks registry. Pro components use a scoped Rails Blocks access token.

## Install

Install the Ruby gem once:

```bash
gem install rails-blocks-cli
```

Run CLI commands from the root of your Rails app.

## Find Components

Use these commands to browse and inspect the registry:

```bash
# 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 accordion
```

## Install Components

Run `install` from the root of your Rails app. If you do not pass `--as`, the CLI asks which format to install when your terminal is interactive. In non-interactive contexts, such as MCP, it defaults to ERB partials.

Before installing components, complete the setup steps in the [Installation guide](https://railsblocks.com/docs/installation). If components render without styling, JavaScript behavior, or required dependencies, revisit that page first.

```bash
# 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_component
```

Default paths:

- ERB partials: `app/views/shared/<component>/`
- ViewComponents: `app/components/<component>/`
- Stimulus controllers: `app/javascript/controllers/`

The installer also installs the component's required Stimulus controllers when they are not already present. Existing files are skipped unless `--force` is passed.

## Update Components

Use `diff` before `update` to review local changes:

```bash
# 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 partial
```

Updates do not require `--force`. Reserve `--force` for install-time overwrites.

## Update Stimulus Controllers

Stimulus controller updates write to `app/javascript/controllers`:

```bash
# 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 --pro
```

Free controllers can be fetched anonymously. Pro controller updates use your Rails Blocks token.

## Use Pro Components

Pro components require an access token. The CLI can open a browser approval flow or send a magic-code approval email:

```bash
# 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_component
```

## Useful Commands

| Command | Description |
| ------- | ----------- |
| `rails-blocks doctor` | Check registry, API, and token configuration. |
| `rails-blocks docs tooltip` | Read component docs from the public registry or Pro API. |
| `rails-blocks docs accordion` | Show docs or recommended web/markdown links such as `https://railsblocks.com/docs/accordion`. |
| `rails-blocks examples modal` | Print usage examples for a component. |
| `rails-blocks logout` | Remove the local Rails Blocks API token. |

## AI Instructions

When using this page as context:

- Prefer dry runs before install or update commands.
- Ask which output format the user wants when it is unclear: shared partials, ViewComponent, or plain examples.
- For Pro components, verify the user has run `rails-blocks login` or provided a scoped token.
- Do not suggest `--force` unless the user explicitly wants to overwrite existing files.