CLI Reference

All commands available from the terminal.

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 45 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

`tool`

Run any of the 45 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, and defaults to the working directory. --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), --environment is that tool’s filter and does not set RAILS_ENV: tool env_config --environment production lists production and boots the app in its usual environment. 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. A custom tool that declares the parameter gets the value both ways, since its schema cannot be read before the app boots.

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.

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 the schema cannot hold - --detail bogus where the parameter takes summary, standard or full, or --limit abc where it takes an integer - is warned about on stderr and the tool’s own default is used. A required parameter has no default, so a value outside its list (--action bogus on migration_advisor) exits 1.

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

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, model files, routes, MCP config validity, introspector health, ripgrep availability, Prism gem, Brakeman gem, listen gem, gitignore security, auto_mount security, schema size, view count, and more.

`watch`

Watch for file changes and auto-regenerate context files.

rails ai:watch
rails-ai-context watch

Requires the listen gem. Watches app/, config/, db/, lib/, rakelib/, test/, spec/.

`init` (standalone only)

Interactive setup for standalone mode.

rails-ai-context init
rails-ai-context init --mcp-only   # MCP config only, no context files

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). --mcp-only skips the second question.

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

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=true or explain=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 users or --table=users
Booleans: --explain (true) or --no-explain (false)
Enums: --detail full
Arrays: --files a.rb b.rb or --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

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