CLI reference
Every command in the CLI's command table: setup, account, work, chat and preferences in excellent, plus the excellent-mcp companion binary. Some are newer than the release on npm.
On this page
Two binaries ship in one package, @excellent-so/cli:
excellent: the command you use. Run bare, it opens the chat REPL.excellent-mcp: the companion binary. Run with no arguments it is the MCP server, speaking stdio to whichever agent registered it.
Warning
Newer than the release on npm. @excellent-so/cli 0.1.0, the version npm
serves (checked October 23, 2026), predates part of this page. It has no
install-agent-mcps, run, verify or receipt verify in either binary, and no
excellent-mcp verification; it answers each with unknown command and exit 2. The
other commands on this page are in 0.1.0. This note comes out with the next release.
Everything below is read from the CLI's command table. If a command is not on this
page, it is not part of the supported surface. excellent-mcp carries a long tail of
internal operator verbs that are deliberately absent from excellent --help and from
here.
Run excellent --help for the same list on your machine, and excellent <command> --help
for a command's own flags.
Getting set up
| Command | What it does |
|---|---|
excellent --version | Print the CLI version. -v is an alias. |
excellent init | Scaffold AGENTS.md and .excellent/{context.md,cli.toml} in the current directory. |
excellent doctor | Health read: runtime, database, providers, keys, coding CLIs, PATH, versions. |
excellent inspect | What resolves here: tool-belt size, skills, MCP registration, context files. |
excellent install-agent-mcps | Register the Excellent MCP server in every detected agent it knows how to configure: 28, listed with their files in Claude Code, Cursor and other agents. --json prints the full report. |
excellent update [--dry-run] | Self-update. Detects npm, binary or source-checkout installs. |
excellent completions <bash|zsh|fish> | Print a shell completion script. |
excellent init takes --force to overwrite an existing AGENTS.md. It has no
--help: passing one runs the command.
Account and consent
| Command | What it does |
|---|---|
excellent login [--as HANDLE] [--workspace ID|SLUG] | Bind this terminal to a local workspace and account. Seals a device token in the OS keychain, never in the database. |
excellent whoami | Show the bound account and workspace. |
excellent logout | Clear the binding. |
excellent accounts | List bound accounts. |
excellent authorize [--all|--minimal|--scopes a,b] [--status] [--revoke] | Choose what the tool belt may do: read, write, terminal, admin. The belt advertises only what you granted. |
Doing work
excellent run
excellent run --agent <role> --task <task-id> [--json]Runs a role against an existing task. Both flags are required.
--agent: the role name.--task: an existing numeric task id. A free-text objective is validated and then refused with a structured hint: the underlying pathway targets task ids only, so file the objective as a task first.--json: emit an envelope on stdout:{ok, command, agent, taskIdOrObjective, taskId?, correlationId, exitCode?}.- Other agent-run flags (
--goal,--cli,--dry-run,--loop) pass through.
Every invocation prints a correlationId on stderr. Exit codes: 0 completed ·
1 not completed · 2 usage or goal refusal.
excellent verify
excellent verify <work-id> [--tenant T] [--bearer-file PATH] [--idempotency-key KEY] [--json]Starts or reads a verification. A work id starts one; a ver_* id reads the status of
an existing one. Defaults to tenant local; supply a real credential with
--bearer-file. Also accepts --token-id, --scopes and --now.
Exit codes: 0 ok · 1 runtime · 2 usage or validation · 3 authorization · 4 not found.
excellent-mcp receipt verify
excellent-mcp receipt verify <pack.json> [--offline] [--pubkey PEM_FILE] [--key-id ID]excellent receipt verify is a different command with the same name: it is the
v0 alias of excellent-mcp evidence verify, it takes an EvidenceBundle rather
than a receipt pack, and it exits 2 on any flag but --offline and --json.
If you pass --pubkey to it you get a usage error, not a verification.
Re-derives a receipt offline, with no database and no network. Checks the canonical payload hash, the Ed25519 envelope signature, the canonical binding, anchoring against the operator-pinned public key, and the ledger anchor. Prints one JSON line.
--pubkey pins the issuer's Ed25519 public key as SPKI PEM; its sha256 fingerprint is
the out-of-band anchor. --offline is accepted because the verifier already is
offline.
Exit codes: 0 verified · 2 usage · 8 unverifiable or invalid.
Chat
Bare excellent opens the REPL. It drives the same tool belt over any model provider,
or through a coding CLI you already have.
| Flag | Meaning |
|---|---|
--provider ID | An HTTP provider plus key: anthropic (default), openai, openrouter, deepseek, groq, together, mistral, xai/grok, ollama, lmstudio, vllm. |
--cli NAME | Route through a local coding CLI instead, using its auth and no API key: claude, codex, gemini, grok, xai, cursor. claude is first-class: full belt and resumable. |
--model ID | Model id. Defaults per provider. |
--base-url URL / --transport openai|anthropic | Custom endpoint and wire dialect. |
--tools P | Tool-belt breadth: product (default), search, core, full. |
--allow a,b,c | Advertise exactly these tools, overriding --tools. |
--no-tools | Connect no belt at all. |
-p "message" | One-shot: run a single turn and exit. |
--json / --output-format text|json|stream-json | Machine-readable output, for CI and pipes. |
--resume [id] / --continue | Continue a saved session. excellent chat sessions lists them. |
--dry-run | Resolve the provider and connect the belt, print JSON, exit. No model call. |
--max-turns N, --budget-tokens N, --budget-wall-ms N | Per-message ceilings. Turn default is 40. |
Keys come from the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY,
OPENROUTER_API_KEY, …), or skip keys entirely with --cli. Sessions auto-save to
~/.excellent/chat-sessions/. excellent chat --help prints the full flag list.
Preferences and appearance
| Command | What it does |
|---|---|
excellent config <list|get|set|unset|path> | CLI preferences in ~/.excellent/cli.toml. A project ./.excellent/cli.toml overrides it. |
excellent theme [name|preview|bg|spinner] | Accent theme, dark/light/auto background, spinner family. |
excellent runtime [status|bootstrap] | Inspect or bootstrap the companion/standalone runtime. Flags: --standalone, --companion, --data-dir DIR, --json. |
excellent bug | Report a bug. Flags: --title, --description, --severity, --email, --yes. |
The companion binary
| Command | What it does |
|---|---|
excellent-mcp | Run the MCP server on stdio. This is what an agent launches. |
excellent-mcp install-agent-mcps | Same as excellent install-agent-mcps. |
excellent-mcp install-skills | Source-checkout only: mirror skills into ~/.claude/skills, register the MCP server, write project hooks, and install the ~/.local/bin shim. |
excellent-mcp uninstall-skills | Reverse it, in a source checkout. Removes only Excellent's own symlinks and MCP entries. It does not remove the entries an npm install wrote; delete those by hand. |
excellent-mcp status | Show what is currently installed. |
excellent-mcp verification commands | List the canonical verification API commands and their MCP names. |
excellent-mcp verification observables | List the observables this tier can decide, and the rules for binding one. |
Environment variables
| Variable | Effect |
|---|---|
EXCELLENT_DATA_DIR | Override ~/.excellent/ (the local database and sessions). |
EXCELLENT_HOME | Path to an Excellent monorepo root. Auto-detected when possible. |
EXCELLENT_MCP_PROFILE | Tool-belt profile the MCP server advertises. Default product. |
EXCELLENT_MCP_ALLOW | The actual security boundary, enforced at dispatch. The profile is a menu; this is the fence. |
CLAUDE_CONFIG_DIR | Override ~/.claude/. |
For installer variables (EXCELLENT_CLI_URL, EXCELLENT_SOURCE, EXCELLENT_DRY_RUN,
EXCELLENT_ALLOW_UNVERIFIED), see Install.
Commands that do not exist
Asked for often, and absent on purpose:
excellent uninstall: remove it by hand. Install has the steps.excellent export: not implemented. The local database is a file in~/.excellent/.excellent status:excellent-mcp statusreports installer state, not workspace state. Useexcellent doctor.
An unknown command exits 2 and tells you to run --help.