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.

Install the CLI

Install the Ruby gem once, then run commands from the root of your Rails application.

Terminal 
gem install rails-blocks-cli

Find components

Browse the public registry, search for a component, or inspect its metadata before installing anything.

Terminal 
# 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

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.

Terminal 
# 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 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.

Terminal 
# 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

Update Stimulus controllers

Stimulus controller updates write to app/javascript/controllers. Free controllers can be fetched anonymously; Pro controller updates use your Rails Blocks token.

Terminal 
# 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

Use 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.

Terminal 
# 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

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.
Installation
MCP

Table of contents

Get notified when new components come out