# CLI: connect Claude Code and Codex from your terminal

The Context Mode CLI signs your terminal in and points Claude Code and Codex at the gateway. 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 Claude Code or Codex to Context Mode Gateway, or takes them off it again.

Clients

Claude Code, in `~/.claude/settings.json`, and Codex, in `~/.codex/config.toml`.

Measured result

Not measured on its own. For the gateway as a whole, see [Benchmarks](https://context-mode.com/docs/benchmarks#pooled).

Limits

Needs Node 20.12 or later. It edits config files for Claude Code and Codex only. It needs a Claude Code or Codex login on this machine to sign in.

## Run it

You do not need to install anything. npx downloads the current version and runs it:

```
npx @context-mode/cli
```

This page describes version 0.4.0. 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 Claude Code and Codex |
| 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 Claude Code and Codex |

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 Claude Code and Codex 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 ones 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. `--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 Claude Code, Codex or both. 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. The default is the ones installed here. `--client` is the old name and still works. |
| --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 two agents, the most serious code wins.

### 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 Claude Code and Codex, so they talk to Anthropic and 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. The default is both. |
| --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.

### 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: `model_provider = "context-mode"`, only when it names our provider, and the `[model_providers.context-mode]` table.

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.

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 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. Claude Code and Codex send 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.context-mode.com](https://console.context-mode.com), 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.

## FAQ

### Do I have to install the CLI?

No. `npx @context-mode/cli` runs it without an install. Install it globally only if you want the short `context-mode-cli` command.

### Does it install a plugin or a background service?

No. It edits one config file per agent, keeps a backup, and stores one device key. Nothing keeps running.

### Can I see the change before it writes?

Yes. `setup --dry-run` and `disconnect --dry-run` show the change and write nothing.

### How do I stop using Context Mode?

Run `npx @context-mode/cli disconnect`, then `logout`. Your agents talk to Anthropic and OpenAI directly again.

### Does it work in CI or a script?

Yes. Use `setup --yes` to write without a question, `setup --check` to test the config, and `status --json` to read the state. Sign-in still needs a browser once.

[Quick start](https://context-mode.com/docs/quick-start) [Open the console](https://console.context-mode.com) [FAQ](https://context-mode.com/docs/faq)