# 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](https://contextmode.ai/docs/quick-start#apps).

Measured result

For the gateway as a whole, see [Benchmarks](https://contextmode.ai/docs/benchmarks#pooled).

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](https://contextmode.ai/docs/quick-start#apps). 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:

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](#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](#which-apps) ; 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](#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](#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_URL` sends Claude Code's requests through the gateway.
- `ANTHROPIC_CUSTOM_HEADERS` gets 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_provider` picks the provider below. Codex's default, `openai`, is switched without asking. Any other provider is yours, and setup asks first.
- `requires_openai_auth = true` is 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_KEY` that is only exported in your shell is not sent, so setup tells you to run `printenv 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](https://claude.com/docs/third-party/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 login` or set as `ANTHROPIC_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 `/login` or set as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. `auth.json` and `settings.json` stay 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-key` line of `ANTHROPIC_CUSTOM_HEADERS`. Your other header lines stay.
- The `env` block 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](#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](#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](https://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.

[Quick start](https://contextmode.ai/docs/quick-start) [Open the console](https://console.contextmode.ai)
