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

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.

> **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](https://www.excellent.so/docs/claude-code-and-cursor#every-agent-and-its-file). `--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](https://www.excellent.so/docs/install).

## Commands that do not exist

Asked for often, and absent on purpose:

- `excellent uninstall`: remove it by hand. [Install](https://www.excellent.so/docs/install) has the steps.
- `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`.

Source: https://www.excellent.so/docs/cli
