Skip to content

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

CommandWhat it does
excellent --versionPrint the CLI version. -v is an alias.
excellent initScaffold AGENTS.md and .excellent/{context.md,cli.toml} in the current directory.
excellent doctorHealth read: runtime, database, providers, keys, coding CLIs, PATH, versions.
excellent inspectWhat resolves here: tool-belt size, skills, MCP registration, context files.
excellent install-agent-mcpsRegister 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.

CommandWhat 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 whoamiShow the bound account and workspace.
excellent logoutClear the binding.
excellent accountsList 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

Text
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

Text
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

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

FlagMeaning
--provider IDAn HTTP provider plus key: anthropic (default), openai, openrouter, deepseek, groq, together, mistral, xai/grok, ollama, lmstudio, vllm.
--cli NAMERoute 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 IDModel id. Defaults per provider.
--base-url URL / --transport openai|anthropicCustom endpoint and wire dialect.
--tools PTool-belt breadth: product (default), search, core, full.
--allow a,b,cAdvertise exactly these tools, overriding --tools.
--no-toolsConnect no belt at all.
-p "message"One-shot: run a single turn and exit.
--json / --output-format text|json|stream-jsonMachine-readable output, for CI and pipes.
--resume [id] / --continueContinue a saved session. excellent chat sessions lists them.
--dry-runResolve the provider and connect the belt, print JSON, exit. No model call.
--max-turns N, --budget-tokens N, --budget-wall-ms NPer-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

CommandWhat 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 bugReport a bug. Flags: --title, --description, --severity, --email, --yes.

The companion binary

CommandWhat it does
excellent-mcpRun the MCP server on stdio. This is what an agent launches.
excellent-mcp install-agent-mcpsSame as excellent install-agent-mcps.
excellent-mcp install-skillsSource-checkout only: mirror skills into ~/.claude/skills, register the MCP server, write project hooks, and install the ~/.local/bin shim.
excellent-mcp uninstall-skillsReverse 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 statusShow what is currently installed.
excellent-mcp verification commandsList the canonical verification API commands and their MCP names.
excellent-mcp verification observablesList the observables this tier can decide, and the rules for binding one.

Environment variables

VariableEffect
EXCELLENT_DATA_DIROverride ~/.excellent/ (the local database and sessions).
EXCELLENT_HOMEPath to an Excellent monorepo root. Auto-detected when possible.
EXCELLENT_MCP_PROFILETool-belt profile the MCP server advertises. Default product.
EXCELLENT_MCP_ALLOWThe actual security boundary, enforced at dispatch. The profile is a menu; this is the fence.
CLAUDE_CONFIG_DIROverride ~/.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 status reports installer state, not workspace state. Use excellent doctor.

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

Was this page helpful?

Start here

  • StartWhat Excellent does
  • StartInstall
  • StartQuickstart
  • StartConnect an agent
  • StartRun the first task
  • StartRead a result