Docs · CLI reference
The corvi command line.
Every customer-facing corvi command and its flags. The CLI is the same engine the app runs — drive a plan, serve it over MCP, or audit spend, all from the terminal.
Overview
corvi is the headless planning engine. The macOS app is built on top of it; the binary ships inside the app bundle at Corvi.app/Contents/Resources/corvi. Symlink it onto your PATH to call it directly:
ln -s /Applications/Corvi.app/Contents/Resources/corvi /usr/local/bin/corvi
corvi --helpThe customer-facing commands are run (the default), self-review, mcp-serve, mcp-files-serve, capabilities, costs, and symbolicate.
.env auto-loader, so export your keys in the same shell: set -a; . ./.env; set +a. See Configuration.corvi run
Run a grounded planning session against a workspace. With no subcommand, corvi defaults to run.
corvi run --workspace . --prompt "Add retry/backoff to the webhook sender" \
--review --synthesize --export ./planWorkspace & task
| Flag | Default | Description |
|---|---|---|
-w, --workspace <path> | — | Path to the repository/workspace to ground the plan in. Required. |
-p, --prompt <text> | — | The planning prompt / task description. Required. |
--file <path> | — | Workspace-relative file(s) to seed as context. Repeatable. |
--refine <plan.md> | — | Amend an existing plan: carry a prior plan's contents instead of drafting from scratch. Cheaper than a full rerun. |
--resume <runID> | — | Resume an interrupted run by ID (pass the same --prompt/--workspace). Validates the repo hasn't moved, then re-runs — completed passes are restored from the cache for free. |
Pipeline & models
| Flag | Default | Description |
|---|---|---|
--model <id> | the default drafter | Anthropic model id for the draft pass. |
--review | off | After drafting, have a second-family model review the plan (needs OPENAI_API_KEY). |
--review-model <id> | the default reviewer | OpenAI model id for the review pass. |
--synthesize | off | After review, reconcile findings into a revised final plan. Implies --review. |
--preset <name> | quality | Pipeline preset: quality | allRound | value | fullLocal | claudeCode. Explicit --model / --review-model win. |
--quick | off | Quick Plan: a single-pass, ≤60s grounded sketch, no review. |
--seed-only | off | Only gather the retrieval seed; don't call the model. |
Providers
| Flag | Default | Description |
|---|---|---|
--claude-code | off | Use your Claude Pro/Max subscription instead of an API key. Logs in once via the official claude CLI, which owns auth. Mutually exclusive with --local. |
--local | off | Plan with a local Ollama model — nothing leaves the machine. |
--ollama-model <id> | qwen2.5-coder | Ollama model id (with --local). |
--ollama-host <url> | http://localhost:11434 | Ollama host URL. |
--open-router-key <key> | OPENROUTER_API_KEY | OpenRouter key. Use with --model openrouter/<vendor>/<model>. |
Grounding
| Flag | Default | Description |
|---|---|---|
--semantic | off | Seed the draft with a local semantic (embeddings) search over the repo. |
--embed-model <id> | nomic-embed-text | Ollama embedding model (with --semantic). |
--lsp | off | Use an installed language server (sourcekit-lsp/gopls/…) on PATH for compiler-exact references and signatures. Falls back to text search when absent. |
--parallel-ground | off | Fan out cheap read-only explorer sub-agents to ground before drafting. |
--explorers <n> | 4 | How many explorer sub-agents to fan out with --parallel-ground. |
--explorer-model <id> | a cheap model of the draft family | Model for explorer sub-agents. |
Tools & egress
| Flag | Default | Description |
|---|---|---|
--mcp <server> | none | Enable a discovered MCP server for this run (repeatable; opt-in egress). |
--skill <id> | none | Enable a discovered agent skill by id for this run (repeatable). |
--allow-web | off | Allow web_fetch + web_search for [VERIFY] doc lookups (search needs SEARXNG_URL). |
--max-fetches <n> | 20 | Max external tool calls this run (MCP + web_fetch + web_search). |
--max-cost <usd> | no cap | Per-pass spend ceiling in USD: pause cleanly once a pass's billed cost reaches it. |
Output & cache
| Flag | Default | Description |
|---|---|---|
--export <dir> | — | Write the export package (plan.md + sidecar + evidence + TODO.md) to a directory. |
--save | off | Save the plan into the Corvi app library so it shows up in the app. |
--estimate | off | Print a p50–p90 cost estimate and exit — no provider calls. |
--no-cache | off | Disable the pass cache for this run (always call the provider for every pass). |
--data-dir <path> | $CORVI_DATA_DIR | Override the Corvi data directory (the app's store by default). |
corvi self-review
Model-judged review of a workspace's executed diff: a different-family reviewer reads the change against the plan's requirements and returns a verdict plus findings.
corvi self-review --workspace . --baseline main --task "Add rate limiting" --json| Flag | Default | Description |
|---|---|---|
-w, --workspace <path> | — | Repository whose diff to review. Required. |
--baseline <ref> | HEAD | Git ref to diff against. |
--task <text> | "" | Short task description for the reviewer's requirement background. |
--sidecar <path> | — | Plan sidecar to read the requirements from. |
--min-severity <level> | low | Drop findings below this severity. |
--max-files <n> | no cap | Max files to review; the rest are listed as unreviewed (budget). |
--json | off | Emit the verdict + findings as JSON instead of the human summary. |
corvi mcp-serve
Serve your Corvi plans to a coding agent over MCP (stdio). An MCP client launches it; it reads your plan library and reloads per request. See the MCP server guide for client config and the tool list.
corvi mcp-serve| Flag | Default | Description |
|---|---|---|
--data-dir <path> | $CORVI_DATA_DIR | Override the plan store to serve (the app's store by default). |
The tools are read-only except create_plan, which is on by default and gated by your client's approval prompt. Set CORVI_MCP_ALLOW_CREATE=0 to make it strictly read-only.
corvi mcp-files-serve
Serve one workspace's files to an agent over MCP (stdio), broker-gated and read-only — read_file, search_code, and list_dir, all obeying the broker's deny rules, byte caps, and no-escape-outside-the-workspace rule. It exposes repo access, not plans.
corvi mcp-files-serve --workspace /abs/path/to/repo| Flag | Default | Description |
|---|---|---|
--workspace <path> | — | Absolute path to the workspace whose files are served. Required. |
corvi capabilities
List the MCP servers and agent skills Corvi discovers on this machine. Read-only: nothing is connected, launched, or sent anywhere.
corvi capabilities --workspace .| Flag | Default | Description |
|---|---|---|
-w, --workspace <path> | cwd | Workspace root for project-scoped configs and skills. |
corvi costs
Show recorded LLM spend from the cost ledger. The ledger records every paid call including failures, so this is the authoritative billed total.
corvi costs --since 2026-06-01| Flag | Default | Description |
|---|---|---|
--run <id> | all | Filter to one run by ID (bench or corvi run ID). |
--since <date> | all time | Filter to entries on or after an ISO8601 date, e.g. 2026-06-01. |
--data-dir <path> | $CORVI_DATA_DIR | Override the Corvi data directory. |
corvi symbolicate
Turn the raw {addr, uuid} frames stored by crash reporting back into readable function names and file:line, using dSYMs archived at package time. Offline and read-only — no network, no database.
psql -tA -c "SELECT diagnostic_json FROM crashes WHERE id='…'" | corvi symbolicate| Flag | Default | Description |
|---|---|---|
-i, --input <file> | stdin | Crash JSON file (diagnostic_json or full payload). |
--dsyms <dir> | build/dSYMs | Directory of archived <uuid>.dSYM bundles. |