CLI reference

The comity CLI signs you in, writes agent configuration into your repos, checks your setup and runs inside your agents' hooks. It needs Node.js 22 or newer.

npm i -g https://api.comity.so/cli/comity-cli.tgz
comity --version

Running comity with no arguments shows a home screen: your account, the server, the current repo, which agents are set up there (✔ ready, ! partial, – missing) and the next command to run.

Global options

Unknown commands exit with code 2 and suggest the closest match.

comity login

comity login [--server <url>] [--token <cmt_…>]

Signs in and stores the credentials on this machine.

Without --token (and without COMITY_TOKEN), login uses a browser device flow:

1. The CLI prints a short code and a URL, and opens the URL in your browser (unless COMITY_NO_BROWSER is set).
2. You approve the code in the browser while signed in to Comity.
3. The CLI polls until the server mints a personal token named cli · <hostname> and saves it.

The CLI then verifies the token with GET /v1/me and prints the account, org and role:

✔ Logged in as diego@acme.com · org acme · role member
  Server https://api.comity.so · credentials saved to /home/diego/.config/comity/config.json

Next: run comity init in each repo.

A token must look like cmt_ followed by 43 base64url characters. A rejected token (revoked, expired, or issued by a different server) fails with token rejected by server.

comity login
comity login --server https://comity.internal.example.com
comity login --token cmt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

comity logout

comity logout

Deletes the stored credentials file. If COMITY_TOKEN is set in the environment, the CLI warns that it keeps authenticating.

comity init

comity init [--tools <ids>|all] [--yes] [--server <url>]

Writes Comity's hook, MCP and agent-instruction configuration into the current repository (the git top level; outside a git repo it writes into the current folder and warns).

In an interactive terminal without --tools or --yes, init lists every supported agent, grouped by how Comity reaches it (hooks + MCP, or MCP + instructions only). Agents found on this machine (an executable on PATH or a config folder in your home directory) are pre-selected; when none is found, Claude Code and Codex are. Space toggles, a toggles all, Enter confirms. Cancelling writes nothing (exit 130).

In a pipe, in CI, or with --yes, init sets up claude_code,codex unless --tools says otherwise. Every other agent is opt-in: name it in --tools, or use --tools all.

Files written per agent:

init merges into existing files: it replaces only handlers whose command runs comity hook, only the comity MCP entry and only the marked Comity block of shared instruction files (AGENTS.md, GEMINI.md), keeps everything else, and is safe to re-run. No token is ever written to the repo. The exact contents, approvals and limits are on each agent's page.

After writing, init prints next steps per agent (trust prompts, approvals, user-level MCP entries to paste) and, inside a git repo, the git add / git commit command for the repo files that changed, so teammates get the same setup when they pull.

comity init
comity init --yes
comity init --tools claude_code,omp
comity init --tools cursor,gemini
comity init --tools all --yes

comity status

comity status [--json]

Shows:

• Account: user, org, role, server (and whether it came from the environment or the config file).
• Plan: plan name, active developers this month and repos against the plan's limits, and who is not coordinated when over a limit.
• Repo: path, remote fingerprints, branch, HEAD and merge base with the default branch. A repo without a remote shows (none — hooks are inactive here).
• Your intents: your live intents in this repo with status, branch and claim count.
• Teammates online: other developers' live agents (● active, ○ idle) with tool, branch and intent.

--json prints the same data as one JSON object (server, server_source, token_source, user, org, usage, repo, intents, teammates, plus *_error fields for sections that failed).

comity doctor

comity doctor [--json]

Checks the whole chain from config to a real hook round trip. Each warning or failure prints a › line with the fix.

Exit codes: 0 all checks passed, 1 degraded (warnings), 2 broken (failures). --json prints {"result": "ok" | "warn" | "fail", "checks": [{"name", "level", "detail", "fix"?}]}.

{
  "result": "warn",
  "checks": [
    { "name": "config", "level": "ok", "detail": "server https://api.comity.so [file], token [file], /home/diego/.config/comity/config.json" },
    { "name": "codex hooks", "level": "warn", "detail": "missing SessionEnd", "fix": "run `comity init --tools codex`" }
  ]
}

comity whoami

comity whoami [--json]

Prints the signed-in user, org (name and slug), role, server, and token name and kind, including whether the token came from COMITY_TOKEN or the config file. --json prints the GET /v1/me response plus server. Exits 1 when not logged in.

comity open

comity open [dashboard|messages|conflicts]

Opens the web dashboard (/dashboard, /dashboard/messages or /dashboard/conflicts) in your browser, in the org you are logged in to. The web address is the one you logged in through, or COMITY_WEB_URL. With COMITY_NO_BROWSER set, the URL is printed instead.

comity update

comity update [--check]

Fetches the release manifest (<server>/cli/latest.json) and, if a newer version exists, runs npm install -g <tarball url> and confirms that comity --version on your PATH reports the new version. --check only reports whether an update is available. comity update always fetches the manifest; it ignores the 12-hour throttle and any earlier "no".

If the install fails, the CLI prints the exact command to run by hand and the likely cause (npm not on PATH, files in use on Windows, EACCES permissions).

comity help

comity help [command]

Without an argument, lists all commands. With one, shows that command's usage, options and examples (same as comity <command> --help).

Commands run by your agents

These exist for agent configuration files. You don't run them yourself.

mcp, mcp-headers and auth-header read COMITY_TOKEN first, then the stored login. mcp-headers and auth-header exit 1 when neither exists. comity mcp keeps running and answers every request with an error that says to run comity login, so your MCP client shows the reason. comity mcp writes only protocol messages to stdout. It logs errors to stderr, and with COMITY_DEBUG=1 it also logs each message it forwards.

Updates

Interactive commands (login, logout, init, status, doctor, whoami, open, and the home screen) check for a newer CLI at most once every 12 hours, with a 1.5-second timeout. The hook, mcp, mcp-headers and auth-header commands never check.

• In a terminal, the CLI asks Update now? (Y/n). Answering no silences that version for 24 hours.
• Otherwise it prints one line on stderr.

Turn checks off with --no-update-check, COMITY_NO_UPDATE_CHECK=1, or by running in CI (CI set). The result of the last check is cached in update-check.json next to the config file.

Files

machine_id is a random UUID. The server only receives a hash of it, and an HMAC of your worktree path keyed by it; raw local paths never leave your machine.

Exit codes

See Environment variables for everything the CLI reads from the environment.