CLI Reference
All rails-ai-context commands available from the terminal, with their flags.
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" }
}
}
}
- Paths stay relative, so a committed file means the same thing on every machine. Claude Code, Codex, OpenCode, Copilot CLI (
.github/mcp.json) and the Cursor CLI start a server in the folder they were launched in, and the Cursor editor in the project's folder, so their configs name the app from the workspace (api). VS Code has a name for the folder its config sits in,${workspaceFolder}, so its config names the app from it (${workspaceFolder}/api). The Cursor CLI passes${workspaceFolder}on as literal text, so a Cursor entry an earlier release wrote with it is rewritten by the nextinitin the folder. - The command form is each app's own: the bare binary where the gem is not in the app's Gemfile.lock,
bundle execwhere it is, withBUNDLE_GEMFILEnaming the Gemfile the app's bundle reads - its own (a linked one by the link's name, so its lockfile stays beside it), else the one itsconfig/boot.rbnames, as a monorepo's apps share one, else the onebundle execrun inside the app would find - sincebundle execstarted in the workspace would look for one there. RAILS_AI_CONTEXT_SERVER_NAMEputs the app first in the name the server announces. VS Code names every tool after that name and keeps 13 characters of it, so without it every app's tools would startrails-ai-cont. It is a variable rather than a flag so that an app whose bundle pins an older gem ignores it and starts.- A bare
rails-ai-contextentry left in the folder is replaced, since it would serve the folder itself, and so is an entry under a name the gem gives an app in this folder (its folder name or path) when that app's folder is gone, or the app now goes by another name because an app with the same folder name arrived. An entry namedrails-ai-context-...that runsrails-ai-context serveis the gem's: dropping an AI tool removes it from that tool's config. One that runs no command, such as an HTTP entry of your own under either name, is left alone, and so is a second entry you named yourself for an app (rails-ai-context-api-2included), one that names its app through a variable the tool expands (${userHome}), and one naming an app outside the folder. - A config that does not parse as JSON, or holds comments a rewrite would drop, is left as it is, with a warning that names the entry to add by hand. Trailing commas, which VS Code's and OpenCode's take, are read under json 2.9 or later; Claude Code's
.mcp.jsonand Cursor's.cursor/mcp.jsonare held to plain JSON, so a comment or trailing comma there is reported as one the client cannot read. An empty one is filled, and a byte order mark at the head of one stays. --app-pathnaming a folder of apps sets that folder up the same way; every other command lists the apps below it.- An app whose bundle is not installed yet (a Gemfile and no lockfile) is served by this binary unless its Gemfile names the gem, or pulls gems in from other files (
eval_gemfile,gemspec) that could.
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
- Strings:
table=users - Booleans:
explain=trueorexplain=false - Enums:
detail=full - Arrays:
files=a.rb,b.rb - Spaces:
pattern="has_many :posts"
Thor format
rails-ai-context tool tool_name --key value --key2 value2
- Strings:
--table usersor--table=users - Booleans:
--explain(true) or--no-explain(false) - Enums:
--detail full - Arrays:
--files a.rb b.rbor--files a.rb,b.rb - Spaces:
--pattern "has_many :posts"
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