CLI Reference

All rails-ai-context commands available from the terminal, with their flags.

Quickstart · Tools Reference · Standalone · Configuration


Two CLI interfaces

Context Command prefix Example
In-Gemfile (Rake) rails ai: rails 'ai:tool[schema]' table=users
Standalone (Thor) rails-ai-context rails-ai-context tool schema --table users

Both provide the same 35 tools and functionality.


Commands

serve

Start the MCP server.

rails ai:serve                                        # stdio (default)
rails ai:serve_http                                   # HTTP transport
rails-ai-context serve                                # stdio (default)
rails-ai-context serve --transport http --port 6029   # HTTP transport
Option Default Description
--transport stdio stdio or http
--port http_port from config, else 6029 HTTP listen port
--no-boot off Skip booting the app; answer from source alone

Ctrl-C or SIGTERM stops the HTTP server and exits 0. Requests still running get 3 seconds, then Puma's own grace period of 5, before they are cut off, and the process exits within 15 seconds of the signal whatever else is still running.

The server announces itself to the client as server_name from config, else rails-ai-context. The RAILS_AI_CONTEXT_SERVER_NAME environment variable takes the place of that default for one process; a server_name the app sets itself still wins. A workspace entry sets the variable to put its app first, since VS Code names every tool after the announced name and keeps 13 characters of it.

tool

Run any of the 35 MCP tools from the terminal.

# Rake syntax
rails 'ai:tool[schema]' table=users detail=full
rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
rails 'ai:tool[model_details]' model=User

# Thor syntax
rails-ai-context tool schema --table users --detail full
rails-ai-context tool search_code --pattern "publishable?" --match-type trace
rails-ai-context tool model_details --model User
Option Description
--list List all available tools
--json Output as JSON (-j after the tool name)
--help After the tool name, print that tool's parameters. Rake: help=true
--no-boot Skip booting the app; answer from source alone

Global options may be typed before or after the command name: rails-ai-context --app-path /srv/app doctor and rails-ai-context doctor --app-path /srv/app run the same check.

--app-path names the Rails root, taken as given. Left out, every command that reads an app finds it the way bin/rails and Bundler do: the working directory if it is an app, else the nearest app root above it (a directory with config/application.rb, config/environment.rb, or a bin/rails that boots an app or an engine; never $HOME, node_modules or a gem install), else the one app a level or two below it - looked for everywhere but /, $HOME and the directories above it, which hold too much to search. A root found by its bin/rails alone, with no app source, reads the app below it that bin/rails names as APP_PATH (a monorepo's root), else its test/dummy or spec/dummy app (an engine whose code is all in lib/). A walk names the app it chose on stderr, as [rails-ai-context] using app at a/, so serve keeps stdout clean. A folder holding several apps is refused with one --app-path command per app, and tool --list there lists the tools without an app. The chosen root is the process's working directory for the rest of the run, so init, the config and every file written land in it. --environment names the RAILS_ENV to boot under. Left out, it resolves the way Rails resolves its own environment: the ambient RAILS_ENV, then RACK_ENV, then development, reading an empty value as unset. So an app whose config/boot.rb refuses to run without the variable still gets booted rather than answering nothing. Name it explicitly on a machine that runs more than one environment, because the environment decides which database configuration the booted tier reads.

After the name of a tool that declares an environment parameter of its own (env_config, or config --section env_config), --environment is that tool's filter and does not set RAILS_ENV: tool config --section env_config --environment production lists production and boots the app in its usual environment. The section's name is read in any capitalisation. Set RAILS_ENV through the environment variable, or put --environment before the command name, to boot in another one. Every other tool reads the flag as RAILS_ENV, and so does config with any other section: tool config --section gems --environment production boots the app in production. A custom tool that declares the parameter gets the value both ways, since its schema cannot be read before the app boots.

The ten tools that became rails_get_config sections still answer by their old names: tool gems runs config --section gems. tool gems --help prints "rails_get_gems - runs the gems section of rails_get_config (notable gems by category)." and that section's parameters alone. A mistyped old name is suggested: tool gemz answers "Unknown tool 'gemz'. Did you mean 'gems'?". A bare word after an old name gets that section's flag: tool gems auth answers "'auth' is not a flag - did you mean '--category auth'?".

Inside an app, or with --app-path, tool <name> --help describes the tool that app serves. It reads .rails-ai-context.yml and boots nothing. A tool or section skip_tools turned off answers "rails_get_env is turned off in this app: skip_tools lists it ..." and exits 1. With the app section off, tool config --help marks section required and says "Required: the app section is turned off in this app." A skip_tools set in an initializer is not seen, since help boots nothing. Outside an app help describes the gem's own tools.

Exit status

tool exits 0 when the tool answered and 1 when it could not. A required parameter you did not pass, a flag with no value after it, a bare word where a flag belongs, and an unknown parameter all exit 1 and say which one. So does a refusal on policy - a path outside the app root, a sensitive file, a SQL statement the read-only validator blocks - because the question went unanswered. So does a tool that fails unexpectedly: the answer starts Tool <name> failed:.

A thing that is simply not there is an ordinary answer and exits 0: a file the tool looked for and did not find, a search with no matches, a directory the --path names that does not exist. A tool that needs a booted app and is run with --no-boot (query, runtime_info) prints [UNAVAILABLE] with the reason and also exits 0.

A value outside a parameter's list (--format xml on schema, --action bogus on migration_advisor) exits 1 and names the values the parameter takes. The tool is not run, since any other value would answer a question you did not ask. config --section bogus exits 1 the same way, and its answer names the sections that are on in this app. A value of the wrong type is refused too: --limit abc on search_code answers "Error: abc is not a valid limit. Valid: an integer", a boolean takes true or false, and an empty --limit= is refused. So is --no-<param> on a parameter that is no boolean: --no-limit answers "Error: --no-limit is not a valid limit. Valid: an integer", and a string or an array parameter says "a string" or "an array". One value falls back to the tool's own default with a warning on stderr: a --detail level the tool does not have, since every level answers the same question.

The static tier and --no-boot

Every command that reads the app takes --no-boot: tool, serve, context, inspect, facts, preset, watch and init. It skips the boot and answers from source alone, which is what you want on a repo you have just cloned, on an app whose boot is broken, and in CI where booting costs more than the answer.

The same tier is entered automatically when a boot fails, so you get an answer either way. A boot that hangs (an initializer waiting on a service that is down) counts as failed after RAILS_AI_CONTEXT_BOOT_TIMEOUT seconds: 20 for serve over stdio, whose client waits about 30 seconds for its first answer and then gives up, and 60 for every other command. Raise it for an app that is healthy but slow to boot, and for stdio also raise the client's own limit (Claude Code reads MCP_TIMEOUT, in milliseconds), or the client stops waiting first. Answers that need a running app are marked [UNAVAILABLE: ...] rather than guessed, and everything else is tagged [STATIC] instead of [VERIFIED]. docs/COMPATIBILITY.md lists which of the 40 introspectors answer in which tier.

doctor is the exception: diagnosing the boot is its job, so it refuses --no-boot and still exits 1 when the app cannot start.

rails-ai-context tool model_details --no-boot # no boot, no database, no Gemfile
rails-ai-context context --no-boot            # writes CLAUDE.md from source

Tool name resolution

All of these resolve to the same tool:

rails 'ai:tool[schema]'
rails 'ai:tool[get_schema]'
rails 'ai:tool[rails_get_schema]'

Resolution order: exact match → rails_ prefix → rails_get_ prefix → short name (the name with rails_get_ or rails_ removed).

context

Generate static context files.

rails ai:context              # All configured formats
rails ai:context:claude       # Claude only
rails ai:context:cursor       # Cursor only
rails ai:context:copilot      # Copilot only
rails ai:context:opencode     # OpenCode only
rails ai:context:codex        # Codex only
rails ai:context:json         # JSON export
rails ai:context:full         # All formats, full mode

rails-ai-context context                # All
rails-ai-context context --format claude # Specific format
Option Default Description
--format all configured claude, cursor, copilot, opencode, codex, json, all

Without --format, rails ai:context and rails-ai-context context also bring the selected tools' MCP configs up to date, in the command form the install takes now - after bundle remove rails-ai-context that is the bare binary. A tool whose config a workspace above already serves is left to it. rails ai:context:<tool> writes that tool's config along with its files.

The rake tasks ai:context, ai:context:<format> and ai:context_for also read CONTEXT_MODE: CONTEXT_MODE=full rails ai:context overrides config.context_mode for that run. The standalone binary does not read it.

doctor

Run the diagnostic checks and report an AI readiness score.

rails ai:doctor
rails-ai-context doctor
rails-ai-context doctor --strict   # exit 1 when any check fails (CI gate)
rails ai:doctor STRICT=1           # rake equivalent

Checks include: schema existence, pending migrations in every database (and a database that does not exist or does not answer), model files, routes, whether the command each MCP config holds can start (and a Codex entry still holding the Ruby environment an earlier release saved), whether a context run would rewrite the context files, introspector health, ripgrep availability, the Prism and mcp gems, Brakeman gem, listen gem, secret files and .gitignore, auto_mount security, schema size, view count, and more. The Guide lists every check.

At a mountable engine's root, which boots no app of its own, bundle exec rails-ai-context doctor (or rails-ai-context doctor for a standalone install) diagnoses the dummy app the engine's bin/rails boots - test/dummy or spec/dummy - and reads the install at the engine's root: its .rails-ai-context.yml, MCP configs and context files, the ones an editor opened there uses. bin/rails app:ai:doctor reads them there too. Its fixes name the commands that run at the engine's root, such as bundle exec rails-ai-context context, and its context check runs that command into a copy of the files to see which it would rewrite.

Every path the report names is named from where the command was typed, and every command a fix gives runs there. Typed in an app's parent folder (rails-ai-context --app-path shop doctor), the app's files are named shop/..., and a command of the app's goes there first: rails-ai-context --app-path shop context, cd shop && bin/rails db:migrate, git -C shop rm --cached config/master.key. A line for .gitignore names the app's own and is written the way that file reads it, from the app's root: Add to shop/.gitignore: .env.local. Typed in a folder inside the app (app/models), the report names the app's files from its root, as the app names them, while a fix still works where it was typed: cd ../.. && bin/rails db:migrate, git -C ../.. rm --cached .env, rails-ai-context --app-path ../.. context, and Add to ../../.gitignore: .env. rails ai:doctor reads that folder from the shell's PWD, since Rails' rails command and rake move up to the app's root before the task runs. Typed at an engine's root, the dummy app's files read test/dummy/db/schema.rb and the engine's own Gemfile.lock and app/views, a command of the engine's runs "at the engine's root" (bundle install there needs no folder), and one of the dummy app's goes to test/dummy first; typed inside test/dummy, the engine's files read ../../Gemfile.lock and its commands run "in the engine at ../..". A fix that starts with cd leaves the shell in that folder, so type the next one from where doctor ran.

watch

Watch for file changes and auto-regenerate context files.

rails ai:watch
rails-ai-context watch

Requires the listen gem. rails ai:watch needs it in the app's Gemfile; the standalone binary uses the app's when its bundle locks one, and otherwise one installed with gem install listen. Watches app/, config/, db/, lib/, rakelib/, test/, spec/, the pack and engine folders the app's code lives in, and each folder outside those that holds a file a reader reads: bin/, .github/workflows/, .circleci/, .buildkite/, sorbet/ and the mise config folders. An edit to a file at the app root (Gemfile, Dockerfile, Procfile, .gitlab-ci.yml), in a frontend root, or in a folder outside the app is picked up by the next change in a watched folder, or by a restart.

init (standalone only)

Setup for a standalone install, interactive or answered by flags.

rails-ai-context init                                   # asks
rails-ai-context init --tools claude --defaults         # asks nothing: Claude Code, MCP config + context files
rails-ai-context init --tools claude,cursor --cli       # context files only (CLI mode)
rails-ai-context init --tools all --mcp-only            # MCP config only, no context files
rails-ai-context init --tools claude --prune --defaults # remove the files of tools dropped since the last run

Asks which AI tools to configure and what to write: MCP config and context files, context files only (CLI mode), or MCP config only. Creates .rails-ai-context.yml, the MCP config files (except in CLI mode) and the context files (except with MCP config only).

Flag Answers
--tools LIST Which AI tools: claude, cursor, copilot, opencode, codex, comma-separated, or all. Names only, never menu numbers
--mcp What to write: MCP config + context files (the first install's default)
--cli What to write: context files only (CLI mode)
--mcp-only What to write: MCP config only
--prune Yes to every removal question: the generated files of tools dropped since the last run, the gem's MCP entries on a switch to the CLI setup, the generated context files on a switch to the MCP-only setup, and legacy files
--defaults Every question no flag answered, with its default: all five tools and MCP config + context files on a first run, the recorded tools and setup on a re-run; files are kept

A flag init cannot read (--tools vim, or two of --mcp, --cli and --mcp-only) exits 1 before anything is asked or written. A default never removes a file; only --prune does. The install generator takes the same flags, plus --hook for its pre-commit hook question. The copy-paste prompts use them so an AI tool can run the setup in its own shell, and in the MCP setup the closing summary names each tool's next step: the approval or trust step that tool needs before it starts the server. Every question - including a re-run's cleanup of dropped tools, and in CLI mode whether to take the gem's entries out of existing MCP configs - is asked before the app boots and anything is written; with MCP config only, the app is not booted at all.

Run inside an app, init sets up that app (found the way every command finds it: the app root above a subdirectory, or the one --app-path names).

Run in a folder that is no app but holds apps one or two levels down - a workspace, the folder an editor or agent is often opened at - it sets the folder up as a whole:

work/                      <- run `rails-ai-context init` here
  .mcp.json                   one server per app: rails-ai-context-api, rails-ai-context-web
  .cursor/mcp.json ...        (every selected AI tool's MCP config, in the folder it reads)
  api/  .rails-ai-context.yml, CLAUDE.md, ...   each app keeps its own config and context files
  web/  .rails-ai-context.yml, CLAUDE.md, ...

The AI tools and the setup are asked once. On a re-run whose apps recorded different setups there is no one setup to keep, so --defaults without --mcp, --cli or --mcp-only stops with exit status 1 and asks for one. Each app gets its own .rails-ai-context.yml and context files, because its server reads them from its own root; a child process generates them with the install that app's server will run. The folder's MCP configs get one server per app, because a client reads its project config from the folder it opened. Each entry is named rails-ai-context-<app folder> (the whole path where two apps share a folder name; a short hash where the name would pass 30 characters, since Cursor drops a tool whose server and tool names together pass 60) and points --app-path at its app:

{
  "mcpServers": {
    "rails-ai-context-api": {
      "command": "rails-ai-context",
      "args": ["serve", "--app-path", "api"],
      "env": { "RAILS_AI_CONTEXT_SERVER_NAME": "api-rails-ai-context" }
    },
    "rails-ai-context-web": {
      "command": "bundle",
      "args": ["exec", "rails-ai-context", "serve", "--app-path", "web"],
      "env": { "BUNDLE_GEMFILE": "web/Gemfile", "RAILS_AI_CONTEXT_SERVER_NAME": "web-rails-ai-context" }
    }
  }
}

Start the client in the workspace folder. A client started inside one of the apps (Claude Code, Codex and OpenCode still read a config above it) runs each workspace server from there, where the relative path misses; the server says which folder the path was written for. To open an app on its own, run init inside it as well. init warns when an app declares a Ruby other than the one the workspace runs, since every server it starts runs under that one. doctor inside one of the apps finds the workspace's config one or two levels up.

uninstall

Removes what the gem wrote: each AI tool's context files and MCP entries, .rails-ai-context.yml, .ai-context.json, the initializer, the .gitignore lines and the pre-commit hook it installed.

rails-ai-context uninstall
bundle exec rails-ai-context uninstall   # in-Gemfile; then bundle remove rails-ai-context

What you wrote stays: your lines around the markers in a shared CLAUDE.md or AGENTS.md, your rule files, other servers in an MCP config, an entry under the gem's name that starts its server some other way (through Docker, say) or holds a key you added (both named, not touched), and a pre-commit hook you changed by hand (named, not touched). Its own config files go even when you edited them: .rails-ai-context.yml and the initializer configure nothing once the gem is gone. An HTTP entry under the gem's name goes too, since only the gem's endpoint answers it. A mount RailsAiContext::Engine line in config/routes.rb is named with its line number for you to delete. In a folder of apps it uninstalls every app below and the folder's MCP configs. It needs no boot. An entry you added by hand to another client's own config from mcp-entry (Claude Desktop and the like) lives outside the app, so remove it there. Where the Claude Code plugin runs the gem, it names the commands that turn the plugin off and take it out (SETUP), since the plugin's server fails once the gem is gone. Its last lines say how to remove the gem itself: bundle remove rails-ai-context when the Gemfile lists it, gem uninstall rails-ai-context once no other app uses the installed copy. Details in the Guide.

mcp-entry

Prints an MCP server entry for a client the install writes no config for: Claude Desktop, Windsurf, Zed, a JetBrains IDE.

rails-ai-context mcp-entry
bundle exec rails-ai-context mcp-entry   # in-Gemfile
{
  "mcpServers": {
    "rails-ai-context": {
      "command": "/Users/you/.rbenv/versions/3.4.1/bin/ruby",
      "args": ["/Users/you/.rbenv/versions/3.4.1/bin/rails-ai-context", "serve", "--app-path", "/Users/you/work/shop"],
      "env": { "PATH": "...", "GEM_HOME": "..." }
    }
  }
}

Such a client starts its servers from its own folder with its own PATH, so every path is absolute. The command is the Ruby the binary runs under, by its full path, which no version manager's shim can swap for the Ruby of the client's folder; --app-path names the app; env carries the gem variables the shell had (PATH, GEM_HOME, GEM_PATH, GEM_ROOT, RUBY_VERSION, BUNDLE_PATH). For an in-Gemfile app the entry runs bundle exec with BUNDLE_GEMFILE naming the app's Gemfile. Merge it into the client's config under the key that client uses for servers, and print it again after the app moves or its Ruby changes. See Other MCP clients.

version

rails-ai-context version
rails-ai-context --version   # or -v

inspect

Print introspection summary as JSON.

rails-ai-context inspect
rails ai:inspect             # short text summary instead of JSON

facts

Print a schema facts summary: tables, associations and dependencies.

rails ai:facts
rails-ai-context facts
rails-ai-context facts --no-boot

preset

Run a named group of tools in one pass: architecture, debugging or migration. With no name it lists the presets.

rails-ai-context preset
rails-ai-context preset architecture
rails 'ai:preset[architecture]'

tree

Print a tree of every command. rails-ai-context help <command> lists that command's options, and so do rails-ai-context <command> --help and -h (after a tool's name, --help is that tool's: tool schema --help).

rails-ai-context tree

Rake tasks (in-Gemfile only)

Task Description
rails ai:context Generate context for all configured formats
rails ai:context:claude Generate Claude context
rails ai:context:cursor Generate Cursor context
rails ai:context:copilot Generate Copilot context
rails ai:context:opencode Generate OpenCode context
rails ai:context:codex Generate Codex context
rails ai:context:json Generate JSON export
rails ai:context:full Generate all formats in full mode
rails 'ai:context_for[claude]' Generate one format by name
rails ai:serve Start MCP server (stdio)
rails ai:serve_http Start MCP server (HTTP)
rails ai:tool List tools or run a tool
rails ai:doctor Run diagnostics
rails ai:watch Watch mode
rails ai:inspect Print introspection summary
rails ai:facts Print schema facts summary
rails 'ai:preset[name]' Run a preset; no name lists them

Tool argument syntax

Rake format

rails 'ai:tool[tool_name]' key=value key2=value2

Thor format

rails-ai-context tool tool_name --key value --key2 value2

JSON output

Add --json for machine-readable output:

rails-ai-context tool schema --table users --json
JSON=1 rails 'ai:tool[schema]' table=users

stdout then holds the envelope (tool, output, error) and nothing else. Whatever the app prints while it boots or while the tool runs - an initializer's puts, Sidekiq's Redis connection line - goes to stderr.

A refused call answers the same way, at exit 1: an unknown tool, an unknown param or a flag with no value gives "error": true with the message in output. When the run stops before the tool (no app found, a failed boot), output says so and the reason is on stderr. A -j right after a flag that may take a value counts here too, since only the tool can tell whether it is that value.


Common workflows

Quick schema check

rails 'ai:tool[schema]' table=users

Trace a method

rails 'ai:tool[search_code]' pattern="process_payment" match_type=trace

Full feature analysis

rails 'ai:tool[analyze_feature]' feature=billing

Check AI readiness

rails ai:doctor

Regenerate after changes

rails ai:context

← Security · Standalone Mode →

Back to Home