Codebrew CLI

Your tools. Your models. One connection.

Connect Claude Code, Codex and OpenCode to Codebrew from your terminal. Save your API key once, choose a model for each tool, and get back to building.

npx @codebrew-ai/codebrew

For a global installation and the short codebrew command:

npm install --global @codebrew-ai/codebrew
codebrew

@codebrew-ai/codebrew is the official npm package. npx codebrew refers to a different npm package.

Requires Node.js 22.13 or newer and current versions of your coding tools. Runs on macOS, Linux and Windows.

First connection

1. Create a key at app.codebrew.in/keys, using your active Hack Pass.
2. Run the command above and choose Get started.
3. Paste the key into the hidden prompt. The CLI validates it using GET /v1/models; it sends no paid inference request.
4. Pick tools and their default models. Only models accessible to that key and compatible with each tool are offered.
5. Review the files, apply the configuration, and start a new tool session.

Missing tools can optionally be installed through their official npm packages. Existing permissions, trust settings, plugins and other providers are preserved. Setup makes Codebrew the default provider/model for the selected tools.

GPT models use the native Responses adapter in OpenCode when your catalog supports it, preserving reasoning and tool calls. Chat-only models keep the Chat Completions adapter. If an older setup rejects GPT 6 Astra tool calls, run npx --prefer-online @codebrew-ai/codebrew link opencode, fully quit OpenCode and any attached server, then reopen it. Starting a new conversation in an already-running process keeps the old connection.

Commands

| Command | Purpose | | --- | --- | | codebrew | Guided setup menu | | codebrew setup | Configure one or more tools | | codebrew login | Validate and save an API key | | codebrew link claude | Configure Claude Code | | codebrew link codex | Configure Codex | | codebrew link opencode | Configure OpenCode | | codebrew model codex | Pick a new default model | | codebrew models --tool codex | List models compatible with Codex | | codebrew status | Inspect local connection status | | codebrew doctor | Check credentials, catalog access and tool configuration | | codebrew restore | Restore the latest configuration backup | | codebrew backups | List earlier backups | | codebrew install opencode | Install a tool with npm | | codebrew dashboard | Open API key management | | codebrew logout | Delete the local saved key; does not revoke it on Codebrew |

Commands also work with npx @codebrew-ai/codebrew, for example:

npx @codebrew-ai/codebrew link codex

Preview and automation

# Preview only; no settings, credentials or backups are written.
codebrew setup --tool claude,codex --model gpt-6-sol --dry-run

# Use a saved key and an explicitly selected model.
codebrew setup --tool codex --model gpt-6-sol --yes

# Structured output for scripts.
codebrew status --json
codebrew doctor --json

# Preview a restore before applying it.
codebrew restore --dry-run
codebrew restore --backup <backup-id> --yes

CODEBREW_API_KEY can supply the key from your secret manager. --key-stdin reads it from a pipe without putting it in command arguments or shell history. Otherwise the CLI reuses its saved key. Keys are never included in normal output or errors.

--yes skips interactive confirmation. With setup, supply --tool; an omitted --model uses a compatible default from the live catalog. --install explicitly enables installation of missing selected tools. Installation invokes npm, so it does not produce JSON output.

Use --home /absolute/isolated-directory for a portable setup or testing. It redirects all CLI and tool configuration paths into that directory and ignores tool-specific directory environment overrides. It does not change your system home directory.

What gets written

| File | Contents | | --- | --- | | ~/.codebrew/api-key | Your saved API key | | ~/.codebrew/key-helper.cjs | Small dependency-free credential helper | | ~/.codebrew/backups/<id>/ | Original configurations and a restore manifest | | ~/.claude/settings.json | Codebrew endpoint, credential helper, model and model aliases | | ~/.codex/config.toml | Codebrew Responses provider, credential helper and default model | | ~/.config/opencode/opencode.json or .jsonc | Codebrew provider, key-file reference and models |

The helper lives outside npm's cache, so clearing the npx cache does not break tool authentication. No shell profile is edited. Existing auth.json files are not modified. CODEBREW_CONFIG_DIR, CLAUDE_CONFIG_DIR, CODEX_HOME and XDG_CONFIG_HOME are respected outside isolated setups.

On Unix, the CLI directory is created with 0700 permissions; credentials, helpers, backups and edited configs use 0600. On Windows, files inherit your user directory's ACLs; use a private user directory. Credentials are stored locally, not encrypted by this package. Backups may contain credentials that were already present in your original configurations.

Setup validates and merges all selected configurations before writing. Invalid JSON/TOML and file symlinks are rejected. Writes are atomic per file; a failed multi-file setup attempts to restore earlier writes. Restore checks that files still match the version installed by Codebrew. If you edited them afterwards, it stops and shows the backup location instead of overwriting your changes.

Restore affects tool settings. It keeps the saved Codebrew key so you can reconnect later. logout deletes that key; use the dashboard to revoke it remotely.

Compatibility

• Claude Code uses /v1/messages, apiKeyHelper, and model aliases pointing at the selected allowed model. Existing API-token environment settings in the selected config are cleared so the helper can supply the Codebrew key. Configured output limits are applied when advertised by the catalog.
• Codex uses /v1/responses and its current command-backed provider authentication. Keep Codex up to date. No deprecated Chat Completions wire protocol or permission bypass is configured.
• OpenCode uses a dedicated codebrew provider and a key-file reference. GPT models use native @ai-sdk/openai Responses when available; chat-only models use @ai-sdk/openai-compatible. The provider label shows the key’s access, such as Codebrew · Testing or Codebrew · Hack Pass. JSONC comments and other providers are preserved. The default and small model both use the selected allowed model.
• Hack Pass compatibility depends on the API formats enabled for each model. A Chat Completions-only pass model is offered for OpenCode, not for Claude Code or Codex. Disabled models are omitted from setup.
• Local project settings, managed configuration, named Codex profiles and shell environment overrides can take precedence. doctor checks effective OpenCode project and environment overrides, selected model adapters, credentials and the installed version. Other tools are checked at the managed configuration level. It does not execute a generation unless you add --live.

Switching the saved key updates authentication for all linked tools. Run setup again to refresh their models for the new key.

Configuration references: Codex providers, Claude Code settings, OpenCode config.

Development

cd apps/cli
npm ci
npm run check
npm run dev -- --help
npm pack --dry-run

Tests use temporary setup roots and mocked catalog requests. They never modify the developer's real tool configuration or send paid inference requests.

Publishing

The package builds before packing and runs its checks before publishing.

cd apps/cli
npm login --registry=https://registry.npmjs.org
npm publish --access public

For future releases without storing a long-lived npm token, configure an npm trusted publisher for Codebrew-Run/codebrew, workflow cli-release.yml, with no environment name. The workflow supports manual dispatch and cli-v* tags. Publishing still requires the npm organization to authorize this package/repository.

Testing access

Create a Testing key at API keys after an admin enables your account. Save it with npx @codebrew-ai/codebrew login, then run npx --prefer-online @codebrew-ai/codebrew link opencode and fully restart OpenCode, including any attached server. Select your model under Codebrew · Testing. doctor shows which access your saved key provides. The same model ID can appear in Testing and Hack Pass; the key determines access and billing.

OpenCode tools and large requests

Run these from the project where the error occurs:

npx @codebrew-ai/codebrew link opencode
npx @codebrew-ai/codebrew doctor
# Optional: uses quota; starts a fresh read-only OpenCode tool-call test.
npx @codebrew-ai/codebrew doctor --live

Version 0.1.4 repairs conflicting Codebrew settings in effective project JSON/JSONC files with private backups, preserving other providers and plugins. Inline OPENCODE_CONFIG_CONTENT must be corrected in your shell; setup reports it instead of claiming success. --home keeps configuration discovery inside the isolated root. Managed organization policies may still override local files.

Validated with OpenCode 1.18.32. GPT tool calls use native Responses. The catalog separates context length from the recommended 16,384-token output default, bounded by configured output limits. An explicit output limit sent to the API is preserved. Model capacity and account allowance remain separate; a short contention wait may occur before dispatch.

The live diagnostic uses the installed OpenCode client and its current project configuration. It asks the read-only plan agent to list top-level JSON filenames with one tool call. Client logs and filenames are not printed by Codebrew. It times out after 90 seconds and reports whether the tool call and final reply completed.

OpenCode setup consolidates older Codebrew provider entries, refreshes model filters from your key’s live catalog, and backs up every changed config file. Run setup from your project directory, then fully quit and reopen OpenCode. Environment-provided inline overrides are reported by doctor and must be corrected in your shell.