CLI Reference

Every command, flag, and exit code.

Commands

Command	What it does
coderrr	Start an interactive session in the current directory
coderrr run "<request>"	Plan the request, show the plan, and implement it once approved
coderrr run	No request given — same as a bare coderrr
coderrr config	Interactively set provider, model, and API key
coderrr config show	Print the current configuration, key masked
coderrr config clear	Delete the config file and any keyring entries
coderrr spec list	List specs in this project with task progress
coderrr spec show [id]	Print a spec's artifacts. Accepts a name, slug, or number; defaults to the latest.
coderrr skills search "<query>"	Search the skill registry
coderrr mcp add <name> <url>	Connect an MCP server. After `--` the argument is a command run over stdio instead.
coderrr mcp list	Configured MCP servers, and which are signed in
coderrr mcp test <name>	Connect to a server and list its tools
coderrr mcp login <name>	Sign in to a server that uses OAuth. `--no-browser` prints the URL instead.
coderrr mcp logout <name>	Discard stored credentials for a server
coderrr mcp enable <name>	Enable a server, or `--off` to disable it without removing the config
coderrr mcp reset <name>	Forget the "always allow" answers for a server
coderrr mcp remove <name>	Remove a server and its remembered approvals
coderrr doctor	Check the local environment
coderrr version	Print the version

It is coderrr version, not --version. There is no --version flag.

Options

coderrr and coderrr run take all three. The spec and doctor commands take --dir only.

Option	What it does	Default
-d, --dir <path>	Workspace root, and the containment boundary	Current directory
-m, --model <name>	Override the configured model for this run	From config
-y, --yes	Skip the approval prompt. A spec is still written and must contain tasks.	Off

Exit codes

Code	Meaning
0	The run succeeded
1	The run failed, no plan was produced, a provider is misconfigured, or the target directory does not exist
130	Interrupted with Ctrl-C. Nothing further was modified.

Declining a plan is not a failure — the exit code reflects whether planning itself succeeded.

Session slash commands

Command	What it does
/help	The command list
/spec	Show the most recent spec
/specs	List every spec in this project
/model [name]	Show or switch the model for this session (not saved)
/auto	Toggle skipping the approval prompt
/mcp	List MCP servers, add or remove one
/mcp add <url>	Connect a server straight away. In effect from your next request — no restart.
/mcp login <name>	Sign in to a server that uses OAuth (`/mcp logout` to undo)
/config	Provider, model, endpoint, masked key, sandbox, verify mode
/doctor	Environment check
/clear	Clear the screen
/exit	Leave the session (aliases: /quit, /q, or Ctrl-D)

Environment variables

Variable	Provider
ANTHROPIC_API_KEY	Anthropic
OPENAI_API_KEY	OpenAI
GOOGLE_API_KEY	Google Gemini
OPENROUTER_API_KEY	OpenRouter
OLLAMA_API_KEY	Ollama-hosted models

These are checked before the OS keyring and before ~/.coderrr/config.toml. See Configuration.

Agent tools

The tools the model can call. Which ones exist depends on the mode: the write tools are absent from the tool list during planning and appear only after you approve.

Tool	Class	What it does
read_file	read	Read a file, optionally a line range
list_dir	read	List a directory
tree	read	Directory tree
grep	read	Search file contents
write_file	write	Create or overwrite a file
edit_file	write	Replace an exact, unique string. No fuzzy fallbacks — the model reads before editing.
move_file	write	Move or rename
delete_file	write	Delete a file
create_spec	system	Start a new spec directory
write_spec	system	Write requirements, design, or tasks
read_spec	system	Re-read the spec mid-run
update_task	system	Mark a task in_progress, done, or blocked
search_skills	system	Query the skill registry
load_skill	system	Fetch a skill's guidance
run_in_sandbox	system	Run a command in the sandbox — never against your working tree
ask_review	system	Ask you a question instead of guessing
finish	system	Declare the phase complete
mcp__<server>__<tool>	mcp	One tool from a connected MCP server. Present in both modes, and asks the first time it is used.

There is no tool that runs commands against your working tree. See Sandbox. Bridged MCP tools are the one class that is present during planning as well as execution — see MCP Servers.

Files on disk

Path	What it holds
~/.coderrr/config.toml	Your settings. Created mode 0600.
~/.coderrr/credentials.json	MCP OAuth tokens, when no OS keyring is available. Mode 0600.
~/.coderrr/history	Interactive session history
.coderrr/specs/NNN-slug/	requirements.md, design.md, tasks.md — meant to be committed
.coderrr/cache/	Transient. Gitignored automatically.
.coderrr/session/	Transient. Gitignored automatically.

Examples

# interactive session
coderrr

# one-shot
coderrr run "add user authentication with JWT"

# one-off model override
coderrr run "tidy the imports" -m gpt-4o-mini

# a different project
coderrr run "fix the flaky test" -d ~/code/api

# no approval prompt
coderrr run "bump the changelog" --yes

# inspect what happened
coderrr spec list
coderrr spec show 003

# connect an MCP server, then check it
coderrr mcp add figma http://127.0.0.1:3845/mcp
coderrr mcp test figma

# environment check
coderrr doctor

Removed in v2

v1	Now
coderrr start	coderrr
coderrr exec "<request>"	coderrr run "<request>"
coderrr analyze "<request>"	coderrr run "<request>", then decline the plan
coderrr config --show / --clear	coderrr config show / config clear
coderrr rollback	git revert — v2 never auto-commits
coderrr market / install / skills	coderrr skills search
-b, --backend <url>	Gone. There is no backend.
--auto-commit	Gone. Version control is yours.
--no-auto-test, --no-auto-retry, --max-retries	Gone. See [agent] in the config.

Full detail in Migrating from v1.