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 as npx @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

CommandWhat it does
npx @context-mode/cliSign in if needed, pick your agents, set them up, check them
loginSign this terminal in, in the browser
setupWrite the gateway settings into each app you pick
statusWho is signed in, and how each agent is set up
doctorCheck the gateway, the device key and each agent's config
logoutSign this terminal out and revoke its device key
disconnectTake 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:

  1. Signs you in, in the browser, when this terminal has no valid device key.
  2. Finds the apps on this machine.
  3. 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.
  4. Writes each one's config, with a backup of the old file.
  5. 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
OptionWhat it does
--agent claude|codex|allWhich 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-desktopClaude Desktop. It switches the app to third-party (gateway) mode. Quit it with Cmd+Q and open it again.
--agent codex-desktopCodex Desktop, the ChatGPT app. It reads the Codex CLI's ~/.codex/config.toml, so this writes that file once.
--agent t3codeT3 Code. It runs Claude Code and Codex, so this writes both their files once each.
--agent opencodeOpenCode: its Anthropic provider in its own opencode.json. Needs your own Anthropic API key.
--agent piPi: its Anthropic and OpenAI providers in its own models.json. Needs your own API key.
--yes, -yWrite without asking. It still never replaces a different base URL or provider.
--dry-runShow the change and write nothing.
--checkWrite nothing. Exit 0 when every chosen agent is set up, 2 when one is not.
--replace-base-urlReplace a different ANTHROPIC_BASE_URL or Codex provider.
--gateway URLUse 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"
OptionWhat it does
--agent claude|codex|allWhich agents. Also claude-desktop, codex-desktop, t3code, opencode and pi. Without it, a terminal asks, and lists only the connected apps.
--dry-runList what it would remove and write nothing.
--yes, -yRemove without asking.
--reason TEXTTell us why you leave. Optional.
--gateway URLAlso 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"

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_…" }

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_…" }
} } } }

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" } }
} }

Quit Pi and run it again.

What setup and disconnect promise

What disconnect removes

Claude Code, in the env block:

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.

Get started free

Context Mode Gateway: your coding agent costs less and remembers your project. Context Mode Engine installs from your terminal.

Start free: 1,000 requests, every feature, no card. After you sign in, the console gives you one command to connect your coding agent.

Read the docs