CLI reference

Every command the installed CLI actually has: setup, account, work, chat and preferences in excellent, plus the excellent-mcp companion binary.

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.

Everything below is read from the shipped 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 MCP-capable agent.
`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.

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 — no database, 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. Removes only Excellent's own symlinks and MCP entries.
`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 three commands.
excellent export — not implemented. The local database is a file in ~/.excellent/.
excellent status — excellent-mcp status reports installer state, not workspace state. Use excellent doctor.

An unknown command exits 2 and tells you to run --help.