CLI
CLI: connect your coding agent from your terminal
The Context Mode CLI signs your terminal in and points your coding agent at the gateway: Claude Code, Claude Desktop, Codex, Codex Desktop, T3 Code, OpenCode and Pi. Run it with npx, with nothing to install, and remove it again with one command.
Key facts
- What it is
- The npm package
@context-mode/cli, run asnpx @context-mode/cli. Seven commands: connect, login, setup, status, doctor, logout and disconnect. - Who it is for
- Anyone who connects a coding agent to Context Mode, or takes it off again.
- Clients
- Claude Code, Claude Desktop, Codex, Codex Desktop, T3 Code, OpenCode and Pi. Each app and the file it writes are in the quick start.
- Measured result
- For the gateway as a whole, see Benchmarks.
- Limits
- Needs Node 20.12 or later. It edits only the config files of the apps it knows. To sign in it needs an Anthropic key, a Claude Code login or a Codex login on this machine.
Run it
You do not need to install anything. npx downloads the current version and runs it:
npx @context-mode/cli
Version 0.12.0 connects Claude Code, Claude Desktop, Codex, Codex Desktop, T3 Code, OpenCode and Pi. The list of apps, the --agent values, the files each app gets and what disconnect removes follow 0.12.0. 0.12.0 writes the address gateway.contextmode.ai; the old address on this page is the same gateway and keeps working. The other parts of this page describe version 0.5.0. To install each app its makers' way first, see Your app. To see the commands in your terminal, run npx @context-mode/cli --help.
To keep it installed, install it globally. The command is then context-mode-cli:
npm i -g @context-mode/cli
context-mode-cli status
The old name from version 0.1.0, context-mode-login, still works and runs the same program.
Commands
| Command | What it does |
|---|---|
| npx @context-mode/cli | Sign in if needed, pick your agents, set them up, check them |
| login | Sign this terminal in, in the browser |
| setup | Write the gateway settings into each app you pick |
| status | Who is signed in, and how each agent is set up |
| doctor | Check the gateway, the device key and each agent's config |
| logout | Sign this terminal out and revoke its device key |
| disconnect | Take Context Mode out of each connected app |
Each one runs as npx @context-mode/cli <command>. Add --help to any of them to print the list.
No command: connect
With no command, the CLI does the whole setup in one go:
- Signs you in, in the browser, when this terminal has no valid device key.
- Finds the apps on this machine.
- Asks which of them to connect. The ones it found are already ticked. Without a terminal to ask in, it takes the Claude Code and Codex installs it found.
- Writes each one's config, with a backup of the old file.
- Sends one test request per agent through the gateway, prints one line for each, then the console address and
Ready.
npx @context-mode/cli
npx @context-mode/cli --agent codex
Options: --agent claude|codex|all picks the agents without asking; all means Claude Code and Codex. --agent claude-desktop, codex-desktop, t3code, opencode or pi picks one of the other apps. --replace-base-url lets it replace a different base URL or Codex provider. --gateway URL uses another gateway.
login
Signs this terminal in. It opens a sign-in link in your browser and waits until you finish there. Then it stores this terminal's device key. In a terminal it then offers the same agent picker as connect. Otherwise it prints the next command to run.
To sign in it uses the login your agent already has: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, your Claude Code login, or else your Codex login. It sends that only to the gateway, and never prints it or writes it anywhere.
npx @context-mode/cli login
npx @context-mode/cli login --label work-laptop
Options: --label NAME names this terminal in the console. The default is the host name. --gateway URL uses another gateway.
setup
Writes the gateway settings, and the device key once you are signed in, into the config of each app you pick. It shows the change and asks before it writes. It makes no network call. See What setup writes.
npx @context-mode/cli setup --dry-run
npx @context-mode/cli setup --agent claude --yes
npx @context-mode/cli setup --check
| Option | What it does |
|---|---|
| --agent claude|codex|all | Which agents, with no question. all means Claude Code and Codex. Without it, a terminal shows a list; otherwise it takes the ones installed here. --client is the old name and still works. |
| --agent claude-desktop | Claude Desktop. It switches the app to third-party (gateway) mode. Quit it with Cmd+Q and open it again. |
| --agent codex-desktop | Codex Desktop, the ChatGPT app. It reads the Codex CLI's ~/.codex/config.toml, so this writes that file once. |
| --agent t3code | T3 Code. It runs Claude Code and Codex, so this writes both their files once each. |
| --agent opencode | OpenCode: its Anthropic provider in its own opencode.json. Needs your own Anthropic API key. |
| --agent pi | Pi: its Anthropic and OpenAI providers in its own models.json. Needs your own API key. |
| --yes, -y | Write without asking. It still never replaces a different base URL or provider. |
| --dry-run | Show the change and write nothing. |
| --check | Write nothing. Exit 0 when every chosen agent is set up, 2 when one is not. |
| --replace-base-url | Replace a different ANTHROPIC_BASE_URL or Codex provider. |
| --gateway URL | Use another gateway. |
Exit codes: 0 done or nothing to do, 1 refused or a file could not be written, 2 --check found an agent not set up, 3 a conflict was not confirmed. With several apps, the most serious code wins.
Which apps
In a terminal, with no --agent and no --yes, setup shows one list: Claude Code, Claude Desktop, Codex, Codex Desktop, T3 Code, OpenCode and Pi. Each app is marked found or not found, and the found ones are ticked. Space ticks or clears an app, Enter confirms, and Ctrl+C stops with nothing written. Your pick is your yes: there is no second question, except for a conflict with another proxy.
Without a terminal, for example in CI or a pipe, or with --agent or --yes, nothing asks. Setup then takes the Claude Code and Codex installs it finds, so a script never switches Claude Desktop into gateway mode by itself. --agent all connects Claude Code and Codex only. Pick Claude Desktop, Codex Desktop, T3 Code, OpenCode or Pi in the list, or name it with --agent. disconnect asks the same way, and lists only the apps that are connected.
status
Prints the gateway and console addresses, who this terminal is signed in as, the workspace and this device, then one line per agent. It exits 0 when you are signed in and 2 when you are not.
npx @context-mode/cli status
npx @context-mode/cli status --json
Options: --json prints the same facts as JSON for scripts. --gateway URL uses another gateway.
doctor
Checks, one line each: that the gateway answers, that the device key is valid, and that each installed agent is set up. When a check fails, the line names the command that fixes it. It exits 0 when all is well and 1 when something needs a fix.
npx @context-mode/cli doctor
Options: --gateway URL uses another gateway.
logout
Tells the gateway to revoke this terminal's device key, then deletes the key here. The key is deleted here even when the gateway cannot be reached. Your agents keep their config; run disconnect to remove that too.
npx @context-mode/cli logout
npx @context-mode/cli logout --all
Options: --all signs out of every gateway stored on this machine. --json prints the answer as JSON. --gateway URL uses another gateway.
disconnect
Takes Context Mode out of each connected app, so it talks to Anthropic or OpenAI directly again. It removes only what setup wrote. Everything else in the files stays. It lists what it will remove and asks first. See What disconnect removes.
npx @context-mode/cli disconnect --dry-run
npx @context-mode/cli disconnect
npx @context-mode/cli disconnect --agent codex --yes --reason "trying it later"
| Option | What it does |
|---|---|
| --agent claude|codex|all | Which agents. Also claude-desktop, codex-desktop, t3code, opencode and pi. Without it, a terminal asks, and lists only the connected apps. |
| --dry-run | List what it would remove and write nothing. |
| --yes, -y | Remove without asking. |
| --reason TEXT | Tell us why you leave. Optional. |
| --gateway URL | Also treat this gateway's address as ours when removing. |
It exits 0 when it removed everything or there was nothing to remove, and 1 when you said no or a file could not be changed.
What setup writes
Claude Code, in ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json), under env:
"ANTHROPIC_BASE_URL": "https://gateway.context-mode.com",
"ANTHROPIC_CUSTOM_HEADERS": "x-cm-device-key: cmdk_…",
"ENABLE_TOOL_SEARCH": "true"
ANTHROPIC_BASE_URLsends Claude Code's requests through the gateway.ANTHROPIC_CUSTOM_HEADERSgets one line with the device key. Header lines you already have stay.ENABLE_TOOL_SEARCH: Claude Code turns tool search off for any base URL that is not Anthropic's, and then sends every tool in full on every call. This turns it back on. If you set it to something else yourself, setup asks before it changes it.
Only these keys change. Line endings, indentation and the rest of the file stay as they were. Restart Claude Code afterwards.
Codex, in ~/.codex/config.toml (or $CODEX_HOME/config.toml):
model_provider = "context-mode"
[model_providers.context-mode]
name = "context-mode"
base_url = "https://gateway.context-mode.com"
wire_api = "responses"
requires_openai_auth = true
http_headers = { "x-cm-device-key" = "cmdk_…" }
model_providerpicks the provider below. Codex's default,openai, is switched without asking. Any other provider is yours, and setup asks first.requires_openai_auth = trueis needed: without it Codex sends no login to a custom provider. A ChatGPT login and an API key login both work.- Codex sends only its own login. An
OPENAI_API_KEYthat is only exported in your shell is not sent, so setup tells you to runprintenv OPENAI_API_KEY | codex login --with-api-key.
Comments, spacing and every other table stay as they were. Start a new Codex session afterwards.
Codex Desktop reads the same ~/.codex/config.toml, so Codex and Codex Desktop share one write. Quit the app fully (Cmd+Q) and open it again.
Claude Desktop keeps this setting in the app, under Developer → Configure Third-Party Inference…. You can do it there yourself: Help → Troubleshooting → Enable Developer Mode, then Developer → Configure Third-Party Inference… → Connection → Apply Changes (Claude Desktop in-app configuration). setup --agent claude-desktop writes the same entry, named contextmode, and switches the app to third-party mode. On a Mac it reuses the Claude Code login on that Mac, so no API key is written; on other systems, or without that login, pass --api-key with an Anthropic API key. Open that window to check or change the entry. Quit the app fully (Cmd+Q) and open it again.
T3 Code runs the Claude Code and Codex you already have, with their own logins. setup --agent t3code writes the Claude Code file and the Codex file above, once each. In T3 Code, open Settings → Providers, keep CODEX_HOME at ~/.codex, and leave Shadow home path empty, so it reads the file setup writes. Quit T3 Code fully and open it again.
OpenCode, in ~/.config/opencode/opencode.json (or under $XDG_CONFIG_HOME/opencode; an opencode.jsonc you already have is edited in place, with its comments):
{ "provider": { "anthropic": { "options": {
"baseURL": "https://gateway.context-mode.com/v1",
"headers": { "x-cm-device-key": "cmdk_…" }
} } } }
- No API key is written. OpenCode sends your own Anthropic key, stored with
opencode auth loginor set asANTHROPIC_API_KEY, and the gateway passes it on unchanged. - OpenCode has no Claude sign-in since version 1.3.0, so a Claude subscription does not work here.
- The OpenAI provider, and a ChatGPT login, stay as they were. So does every other key in the file.
Quit OpenCode and run it again.
Pi, in ~/.pi/agent/models.json (or $PI_CODING_AGENT_DIR/models.json; comments are kept):
{ "providers": {
"anthropic": { "baseUrl": "https://gateway.context-mode.com",
"headers": { "x-cm-device-key": "cmdk_…", "x-cm-client": "pi" },
"compat": { "sendSessionAffinityHeaders": true } },
"openai": { "baseUrl": "https://gateway.context-mode.com/v1",
"headers": { "x-cm-device-key": "cmdk_…", "x-cm-client": "pi" } }
} }
- The Anthropic base URL has no
/v1, because Pi adds it. - No API key is written. Pi sends your own Anthropic or OpenAI key, stored with Pi's
/loginor set asANTHROPIC_API_KEYorOPENAI_API_KEY.auth.jsonandsettings.jsonstay as they were. - A Claude subscription is not routed: Anthropic does not allow its token in another product. If Pi's Anthropic login is such a token, setup leaves Pi's Anthropic provider alone, says so, and sets only OpenAI. Pi's ChatGPT login is not touched.
Quit Pi and run it again.
What setup and disconnect promise
- A file that does not parse is left alone, and nothing is written.
- They show the change and ask before writing. They never print a login or a key.
- They copy the old file to
<file>.cm-setup-bak-<timestamp>next to it, then write the new one in one step. - If the file changes while the question is open, nothing is written. Run the command again.
- A read-only file is refused. A symlinked file stays a link.
- Running setup again with nothing to change writes nothing.
What disconnect removes
Claude Code, in the env block:
ANTHROPIC_BASE_URL, only when it points at a Context Mode gateway. Another proxy's address is yours and stays.ENABLE_TOOL_SEARCH, only when it is"true"and the base URL above was ours.- The
x-cm-device-keyline ofANTHROPIC_CUSTOM_HEADERS. Your other header lines stay. - The
envblock itself only when nothing else is left in it.
Codex and Codex Desktop: model_provider = "context-mode", only when it names our provider, and the [model_providers.context-mode] table. The two apps share this file, so it goes from both.
Claude Desktop: the contextmode entry goes, the entry you used before is applied again, and the app goes back to its own sign-in.
T3 Code: the Claude Code entry and the Codex entry above.
OpenCode and Pi: the file goes back to how it was before setup, so their providers talk to their own address again.
Before it writes, it sends one short message to the gateway so we know you left, with your --reason if you gave one. It does not wait long, and it works offline too. Restart Claude Code, or start a new Codex session, to use the plain agents. Quit a desktop app, OpenCode or Pi fully and open it again.
To go back to the exact file you had before, copy a .cm-setup-bak- backup over it. disconnect does not delete the stored device key; run logout for that. If your shell profile also exports ANTHROPIC_BASE_URL for the gateway, disconnect tells you to remove it there.
The step report
Since version 0.5.0, each run sends one short report to the gateway at its end, so we can see where setup fails and fix it. It holds the CLI version, the command, your OS, CPU type, Node version and shell name, and for each step its outcome and a short reason code, such as setup fail other_base_url. It never holds a path, a file's contents, a prompt, a name, an e-mail address or a key.
It carries two random ids: one for the run, and one kept in ~/.context-mode/install-id, so a run that stopped before sign-in can be matched to the same machine's next run. The CLI waits at most 1.5 seconds for it and ignores every error. Turn it off with CONTEXT_MODE_TELEMETRY=0 or DO_NOT_TRACK=1.
After setup, the CLI tells you what to do next: restart your agent, ask it anything, and check that the request shows in the console. If its own check of an agent fails, it says so and points at doctor.
The device key
Sign-in gives this terminal a device key that starts with cmdk_. It is stored in ~/.context-mode/credentials.json, readable only by you, one per gateway, and it is never printed. Each connected app sends it in the x-cm-device-key header. The gateway knows this terminal by that key, so if you switch Claude or OpenAI accounts, your data stays in one workspace. The gateway removes the header before a request goes to Anthropic or OpenAI.
Gateway and console addresses
Your agents talk to the gateway, https://gateway.context-mode.com. You open the console, console.contextmode.ai, to sign in and see your workspace.
Every command picks the gateway in this order: --gateway URL, then $CONTEXT_MODE_GATEWAY, then the hosted gateway. It ignores $ANTHROPIC_BASE_URL in your shell on purpose, so an address set somewhere else is never copied into a config file. A self-hosted gateway serves its own console at the same address.