The `chorus` command (published as `@chorus-aidlc/chorus`) does three jobs: it runs the Chorus server, configures the coding agents on your machine, and calls the Chorus MCP endpoint from the shell. Install it globally: ```sh npm install --global @chorus-aidlc/chorus chorus --version ``` Run `chorus --help`, or `chorus --help`, for the complete flag list. ## Commands at a glance | Command | What it does | | --- | --- | | `chorus` | Start the Chorus server (the default with no subcommand). See [Deploy with Docker](/guides/deploy-docker/). | | `chorus upgrade` / `chorus update` | Upgrade the npm-global CLI; optionally refresh configured Chorus plugins with `--plugins`. | | `chorus agents` | Configure this machine's agents — `list` (default), `add`, `remove`, and `run` (launch one). | | `chorus mcp` | Native MCP client — `call` a tool, print your UUID (`whoami`), or `list` callable tools. | | `chorus login` | Authenticate as an agent and save the connection to `~/.chorus/daemon.json`. | | `chorus daemon` | Keep a runtime online so Chorus can wake it. See [Operate the Chorus daemon](/guides/daemon-operations/). | :::note[Renamed in 0.17.0] `chorus init` is now `chorus agents add` (same flags). The per-agent `install-*.sh` scripts are retired — they now just point you at `chorus agents add`. ::: ## Upgrade the CLI and plugins From Chorus 0.20.0, use: ```sh chorus upgrade # CLI only chorus upgrade --plugins # CLI, then configured Chorus plugins chorus update --plugins # alias of upgrade ``` The command works only with a global **npm installation** of `@chorus-aidlc/chorus`. It checks npm's latest stable release, updates the active installation in the same npm prefix, and verifies the installed version. If the installed version is already current or newer, it neither reinstalls nor downgrades; `--plugins` still runs. Source checkouts, linked installs, and installs managed by other package managers are not supported. For an older CLI without this command, install the new release first with `npm install --global @chorus-aidlc/chorus@latest`. ### What `--plugins` refreshes It reads `~/.chorus/daemon.json` and refreshes entries whose type is explicitly set to Claude Code, Codex, Kiro, or Pi, including those with daemon waking disabled. Each entry's `env`, `PATH`, and custom config home determine the target. Shared destinations are updated once; distinct homes are handled separately. The command currently reads only the default file, not the path set in `CHORUS_DAEMON_CONFIG_PATH`. - **Claude Code and Codex:** refresh the Chorus plugin using the host's plugin mechanism. - **Kiro:** refresh Chorus templates from the entry's configured Chorus instance. Upgrade that server first so it serves the new templates. Conflicting instance URLs for one shared destination are reported as incomplete. - **Pi:** stable `>=0.99.0 <2.0.0` uses native MCP and updates only eligible `@chorus-aidlc/chorus-pi` installations. Pi `0.84.4–0.98.x` retains the verified `pi-mcp-adapter@5.0.0` pin. Other adapter constraints and Chorus pins/ranges/tags are preserved and may leave setup or latest refresh incomplete. No update of all extensions, Pi itself, or automatic removal of an existing adapter is performed. See [Pi setup and migration](/reference/agents/pi/). If a host CLI is installed but its Chorus plugin is missing, the command installs the plugin. It preserves registrations and credentials and does not install or upgrade the host CLI. Before changing a config file, it saves a copy as `.chorus-upgrade.bak` (overwritten by the next upgrade). `offline` or unknown entries (including the default OpenCode, OpenClaw, and dsh records), and hosts missing from the entry's `PATH`, are skipped and reported as **INCOMPLETE**. For those hosts, follow the setup or upgrade steps in [Agent platforms](/reference/agents/). ### Completion and activation The command runs without prompts. Exit code **0** means all requested work completed; **1** means failure or an incomplete target. A missing daemon file or an empty agent list counts as success, with nothing to refresh; an unreadable or malformed file is a failure. If the CLI update fails, no plugins are refreshed. A failure on one plugin does not stop later targets, and completed updates are kept (there is no automatic rollback). The npm install step streams its progress and has no timeout. If it fails, inspect the reported npm error; for `EACCES` or `EPERM`, use a user-owned Node installation or have the system npm prefix updated by its administrator. Chorus does not elevate privileges. After an update, start new agent sessions and run `chorus daemon restart` when convenient. Active sessions and the daemon are not restarted automatically. ## Configure agents — `chorus agents` `chorus agents add` is the one command that connects a machine's coding agents to Chorus. It detects the agents you already have installed, installs each one's Chorus plugin through that agent's own plugin mechanism, and captures your Chorus URL and agent key once into `~/.chorus/daemon.json`. For Claude Code, Codex, and the DeepSeek Harness it also writes the credential into that agent's own configuration, so interactive sessions authenticate with no manual environment setup (see [Where the credential goes](#where-the-credential-goes)). ```sh chorus agents add # interactive: detect, pick, configure chorus agents add --all --yes # configure every detected agent, no prompts chorus agents add --agents claude,codex \ --url https://chorus.example.com --api-key cho_xxx ``` Setup can be rerun to add agents or refresh credentials. Supported agents are Claude Code, Codex, Kiro, Pi, OpenCode, OpenClaw, and DeepSeek Harness (dsh). Pi setup selects native MCP for stable `>=0.99.0 <2.0.0` or `pi-mcp-adapter@5.0.0` for `0.84.4–0.98.x`, alongside `chorus-pi`. Missing, unsupported, or uncertain Pi versions receive guidance rather than an unconditional MCP-complete claim. See [Pi](/reference/agents/pi/). Useful flags (`chorus agents add --help` lists them all): - `--agents ` / `--all` — which agents to configure. - `--url` / `--api-key` — supply the credential non-interactively (env: `CHORUS_URL` / `CHORUS_API_KEY`). - `--update-installed` — refresh existing installations. For Pi, this runs `pi update --extensions`; simply repeating `pi install` does not update an already-installed package. - `--dsh-profile ` — the DeepSeek Harness profile to install the bundle into. - `--daemon-wake ` / `--daemon-wake-all` — opt the named (or every) wakeable agent into daemon waking. Wakeable agents (Claude Code, Codex, Kiro, Pi) are added *parked* by default — reachable by `chorus mcp` but not woken by the daemon until opted in here or at the per-agent TTY prompt. - `--daemon-autostart` — also install and enable the daemon boot service (Linux systemd / macOS launchd). - `--no-linger` — skip Linux systemd lingering setup or repair; it does not disable an existing setting. See [daemon operations](/guides/daemon-operations/). - `-y, --yes` — skip confirmations (implied when not a TTY, where you must pass `--agents` or `--all`). List and remove configured agents: ```sh chorus agents # list configured agents (name, UUID, backend) chorus agents remove # remove one (match by name or UUID) ``` `chorus agents` never prints an API key. A listed name or UUID is a valid value for `chorus mcp --agent` or the `CHORUS_AGENT_PROFILE` environment variable. For Codex, `--yes` never authorizes an App Server restart. Successful credential/MCP setup offers a separate interruption warning and consent prompt only in an interactive terminal. See [Codex](/reference/agents/codex/). ## Launch an agent — `chorus agents run` `chorus agents run` starts a configured agent in your terminal with its Chorus connection already wired in — the foreground counterpart to daemon waking. Because a child process cannot change its parent shell's environment, the command injects the connection into the launched agent process directly, so you never export anything by hand. ```sh chorus agents run --name work -- --model opus # launch agent "work"; pass --model opus to it chorus agents run # launch the only configured agent chorus agents run --name work --type codex -- resume # override the backend, then pass `resume` through ``` - **Which agent** — `--name ` picks from `agents[]` in `~/.chorus/daemon.json`. Optional when one agent is configured; with several, pass `--name` (or set `CHORUS_AGENT_PROFILE`), or the command exits with an error rather than guessing. - **What's injected** (into the launched process only — never your shell, never printed): `CHORUS_URL`, `CHORUS_API_KEY`, and `CHORUS_AGENT_PROFILE`. - **Which binary** — defaults to the agent's stored backend; `--type` overrides it. Types map to `claude`, `codex`, `kiro-cli`, `pi`, `opencode`, `openclaw`, and `dsh`. Agents added as OpenCode / OpenClaw / DeepSeek Harness are stored as `offline` (the daemon will not auto-wake them), so pass `--type` explicitly to launch those. - **Passthrough** — everything after `--` goes to the agent verbatim, so its full flag surface is available. The agent inherits your terminal, and `chorus agents run` exits with its exit code. ### Persistent args/env and one-off overrides Each selected `agents[]` entry can hold `args` (string array, default `[]`) and `env` (string-to-string object, default `{}`). Both daemon wakes and foreground launches use them. When `agents[]` is non-empty, entries do not inherit top-level `args` / `env`, and setting them at the top level is an error. See the [daemon guide](/guides/daemon-operations/) for a copyable model/thinking/env example, flat-file migration, validation, and secret-handling precautions. Values are literal, with no shell expansion, dotenv loading, or secret lookup. `env` affects only the launched agent. `CHORUS_*` and the Claude Code nesting variables `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` are reserved (case-insensitively): configuring one is an error rather than being silently dropped. Persistent args cannot override options Chorus manages (session, prompt, protocol, cwd, MCP, or permission controls), and cannot include `--` / `-` separators or flags that only print help or version information and exit. Arguments you pass explicitly at launch are forwarded unchanged, including native resume commands. These checks guard against known conflicts; they are not a sandbox. Each `chorus agents run` rereads the file; the daemon picks up changes only after `chorus daemon restart`. Neither affects agents that are already running. `--type` selects the backend used for validation and override matching; it does not translate backend flags. For the options below only, passing one explicitly in the selected command scope replaces the configured option and its value: | Effective backend | Recognized overrides | | --- | --- | | `claude-code` / `claude` | `--model`, `--effort` | | `codex` | `--model` / `-m` / config key `model`; config key `model_reasoning_effort` | | `kiro` | `--model`, `--effort` | | `pi` | `--model`, `--thinking`, `--provider` | | `opencode` | `--model` / `-m` | | `openclaw` | `--model`, `--thinking` on `agent` (`-m` means message, not model) | | `dsh` | None; use `DSH_PROVIDER` / `DSH_MODEL` env instead | Matching recognizes `--option value`, `--option=value`, and, where listed, `-mVALUE` / `-m=VALUE`. Codex supports `-c key=value`, `-ckey=value`, `-c=key=value`, `--config key=value`, and `--config=key=value`; only the two listed keys participate in precedence, leaving unrelated config entries intact. The backend must support the spelling: for Pi 0.85.1, use separated `--model`, `--thinking`, and `--provider` values, not the equals forms. ```sh chorus agents run --name pi-worker -- --model anthropic/claude-sonnet-4-6 --thinking medium chorus agents run --name codex-worker -- exec --model gpt-5.4 -c model_reasoning_effort=high ``` **Subcommands:** persistent args go after the deepest recognized command: Codex `exec`, `exec resume`, or `resume`; Kiro `chat`; OpenClaw `agent`. Put the explicit override in that same scope: `exec --model chosen`, not `--model chosen exec`. A model option placed before the subcommand does not replace the subcommand's configured model; Codex `-c`/`--config` keys apply across scopes. Without a recognized command, configured args are placed first. Other command paths are not inferred; omit incompatible persistent args and use native passthrough for those paths. **Unknown options:** - Persistent `args` accepts ordinary unknown flags, but cannot guess whether the next token is a value or a prompt. Use `["--future=value"]` if the backend supports it, not `["--future", "value"]`. Known options require their expected values. - Unknown or repeatable options keep their order (configured first, then explicit) within the selected scope; there is no general last-wins guarantee. - After an ambiguous explicit option (an unknown option without an inline value), Chorus stops looking for overrides; put known overrides before it or use a supported inline value. Analysis also stops at the first bare `--` inside agent arguments (after removing the outer Chorus delimiter). - Command discovery stops at a positional prompt, an unknown command, or an ambiguous option, and skips known option values. - All explicit tokens are still forwarded unchanged; checking backend flag and version compatibility is up to you. For Windows `.cmd`/`.bat` limits, see the daemon guide. The Codex daemon further limits persistent args to model options and permitted `-c` / `--config` overrides. Other flags fail before the daemon wakes the agent, even if they work in a foreground session. See [Codex daemon configuration](/reference/agents/codex/#model-options-and-session-continuity). ## Call MCP tools from the shell — `chorus mcp` `chorus mcp` is a native MCP client — a way to call any Chorus tool from a script or terminal without spending model tokens. It replaces the earlier `chorus-api.sh` / `chorus-mcp-call.sh` wrappers. ```sh chorus mcp call '' # call a tool with a JSON argument object chorus mcp call --arg key=value # set one string argument chorus mcp call --arg-file content= # stream a file's raw bytes into an argument chorus mcp whoami # print this agent's own UUID chorus mcp list # list the tools this agent may call ``` `--arg-file` is how large content — a document body, an OpenSpec file — reaches a tool without being re-typed through the model. On success `chorus mcp call` prints the tool result verbatim on stdout; a tool or transport error goes to stderr with a non-zero exit code. Identity resolves in this order: `--agent ` → explicit `--url` + `--api-key` flags → `CHORUS_AGENT_PROFILE` → `CHORUS_URL` + `CHORUS_API_KEY` → the single configured agent when only one exists. ## Connection environment variables | Variable | Meaning | | --- | --- | | `CHORUS_URL` | The Chorus instance URL. | | `CHORUS_API_KEY` | An agent API key (`cho_…`). | | `CHORUS_AGENT_PROFILE` | Optional name or UUID of the configured agent to act as. When set, `chorus mcp` reads that agent's key from `~/.chorus/daemon.json`, so you need not export `CHORUS_API_KEY`. | Daemon-woken sessions receive `CHORUS_AGENT_PROFILE` automatically; you only set it by hand for an interactive shell that should act as a specific configured agent. ## Where the credential goes `chorus agents add` always writes the validated credential to `~/.chorus/daemon.json` (mode `0600`; the key is never echoed). For three agents it also seeds the agent's own configuration so interactive sessions authenticate without any manual export: | Agent | Also written to | | --- | --- | | Claude Code | The `env` block of `~/.claude/settings.json` (honors `CLAUDE_CONFIG_DIR`). | | Codex | `~/.codex/.env` (honors `CODEX_HOME`); Codex reads its key from the environment through a keyless `config.toml` entry. | | DeepSeek Harness | `$DSH_HOME/.env`. | Kiro, OpenCode, and OpenClaw read their credential from their own installed configuration or, for a daemon-woken Kiro, from the per-wake environment the daemon exports. ## For agents - **Triggers.** You reach this page to install or upgrade the CLI, configure an agent (`chorus agents add`), or call a Chorus tool from the shell (`chorus mcp call`). - **Constraints.** Prefer `chorus mcp call '' --arg-file content=` for document-mirror and other large-content calls; fall back to `chorus-api.sh` / `chorus-mcp-call.sh` only when `chorus` is not on `PATH`. Never paste an API key onto a command line or into shell history — let `chorus agents add` / `chorus login` capture it. - **Cite.** Run `chorus --help` and `chorus --help` for the authoritative flag surface; it always matches the installed version. ## Related - [Connect an agent runtime](/guides/operator-onboarding/) — the step-by-step setup walkthrough. - [Operate the Chorus daemon](/guides/daemon-operations/) — keep a runtime online. - [MCP tools catalog](/reference/mcp-tools/) — every tool `chorus mcp` can call.