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.

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

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.

npx @context-mode/cli setup --dry-run
npx @context-mode/cli setup --agent claude --yes
npx @context-mode/cli setup --check

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 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.

npx @context-mode/cli disconnect --dry-run
npx @context-mode/cli disconnect
npx @context-mode/cli disconnect --agent codex --yes --reason "trying it later"

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 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, 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.