Skip to content

bjesuiter/codex-switcher

BranchesTags

Repository files navigation

cdx

Switch the coding-agents pi, codex and opencode auth between multiple openAI Plus and Pro accounts.

Latest Changes

1.8.6

Features

  • Add Linux cdx keyring check for focused gnome-keyring dependency/runtime checks plus a secure-store probe.
  • Add Linux cdx keyring install to install required keyring packages on Debian/Ubuntu/Mint, with --yes and --skip-check support.
  • Expand Linux cdx doctor secure-store remediation with deeper guidance and step-by-step follow-up checks when Secret Service/keyring access fails.

Fixes

  • When Linux secure-store access fails because the keyring is locked, cdx now prompts you to unlock it and retry instead of only surfacing a generic error.

Internal

  • Update dependencies and tooling: @bomb.sh/tab, @clack/prompts, @types/bun, @types/node, and tsdown.

see full changelog here: https://github.com/bjesuiter/codex-switcher/blob/main/CHANGELOG.md

Why codex-switcher?

Anthropic has a $100/month plan, but OpenAI only offers $20 and $200 plans. So: switching between two $20 plans is the poor man's $100 plan for OpenAI. ^^

Supported Configurations

  • OpenAI Plus & Pro subscription accounts: Log in to multiple OpenAI OAuth accounts and switch the active credentials.
  • OpenCode auth target: Writes active credentials to ~/.local/share/opencode/auth.json.
  • Pi Agent auth target: Writes active credentials to ~/.pi/agent/auth.json (or $PI_CODING_AGENT_DIR/auth.json).
  • Codex CLI auth target: Writes active credentials to ~/.codex/auth.json when id_token is available.

Requirements

  • macOS (uses Keychain), Windows (uses Windows Credential Manager), or Linux (uses Secret Service/keyring)
  • Bun runtime

Platform Support Status

  • macOS: stable
  • Windows: beta
  • Linux: beta

Install

bun add -g @bjesuiter/codex-switch

This exposes the cdx binary globally.

Usage

macOS (stable)

  1. Install Bun
  2. Install cdx
  3. Run and verify:
    • cdx login
    • cdx status
    • cdx switch
    • cdx relogin <account-id-or-label>
  4. Confirm auth files are written correctly after switching:
    • ~/.local/share/opencode/auth.json (or $XDG_DATA_HOME/opencode/auth.json)
    • ~/.codex/auth.json
    • ~/.pi/agent/auth.json (or $PI_CODING_AGENT_DIR/auth.json)
  5. Credentials are stored in macOS Keychain.

Windows (beta)

Windows support is test-ready and suitable for friend/beta testing, but is not yet production-proven by broad real-world testing.

  1. Install Bun
  2. Install cdx
  3. Run and verify:
    • cdx login
    • cdx status
    • cdx switch
    • cdx relogin <account-id-or-label>
  4. Confirm auth files are written correctly after switching:
    • %LOCALAPPDATA%\\opencode\\auth.json
    • %USERPROFILE%\\.codex\\auth.json
    • %USERPROFILE%\\.pi\\agent\\auth.json (or %PI_CODING_AGENT_DIR%\\auth.json)
  5. If prompted about secure-store fallback, explicitly choose whether to allow it for testing.
    • Non-interactive override (if you accept the risk): CDX_ALLOW_SECURE_STORE_FALLBACK=1

Linux (beta)

Linux support is test-ready and suitable for friend/beta testing, but is not yet production-proven by broad real-world testing.

  1. Install Bun
  2. Ensure a Secret Service backend is available (for example GNOME Keyring with secret-tool)
  3. Install cdx
  4. Run and verify:
    • cdx login
    • cdx status
    • cdx switch
    • cdx relogin <account-id-or-label>
  5. Confirm auth files are written correctly after switching:
    • ~/.local/share/opencode/auth.json (or $XDG_DATA_HOME/opencode/auth.json)
    • ~/.codex/auth.json
    • ~/.pi/agent/auth.json (or $PI_CODING_AGENT_DIR/auth.json)
  6. If prompted about secure-store fallback, explicitly choose whether to allow it for testing.
    • Non-interactive override (if you accept the risk): CDX_ALLOW_SECURE_STORE_FALLBACK=1

Please report the full command output and platform info (cdx status) for any failures.

Common command examples (all platforms)

Add your first account:

cdx login

Switch between accounts:

cdx switch
cdx switch --next
cdx switch <account-id-or-label>

Label accounts:

cdx label
cdx label <account> <new-label>

Interactive mode:

cdx

Use the legacy macOS keychain implementation (if needed):

cdx --secret-store legacy-keychain switch
cdx --secret-store legacy-keychain status

Migrate legacy macOS keychain entries to cross-keychain (auto) and update config:

cdx migrate-secrets

Commands

Command Description
cdx Interactive mode
cdx login Add a new OpenAI account via OAuth (recommended default flow; supports manual URL copy/paste callback completion with optional clipboard copy assist)
cdx login --device-flow Add account using OAuth device flow (may fail on some VPS/server IPs due to Cloudflare challenges)
cdx relogin Re-authenticate an existing account via OAuth
cdx relogin --device-flow Re-authenticate interactively using OAuth device flow (may fail on some VPS/server IPs due to Cloudflare challenges)
cdx relogin <account> Re-authenticate a specific account by ID or label
cdx relogin <account> --device-flow Re-authenticate specific account using OAuth device flow (may fail on some VPS/server IPs due to Cloudflare challenges)
cdx switch Switch account (interactive picker)
cdx switch --next Cycle to next account
cdx switch <id> Switch to specific account
cdx label Label an account (interactive)
cdx label <account> <label> Assign label directly
cdx status Show account status, token expiry, and usage
cdx migrate-secrets Migrate macOS legacy keychain entries to cross-keychain and switch config to auto
cdx doctor Show auth file paths/state and runtime capabilities
cdx doctor --check-keychain-acl Detect macOS keychain ACL/runtime mismatches (cdx/Bun vs legacy security CLI), warn about prompt-heavy setups, and suggest cdx migrate-secrets (slow)
cdx keyring check Run focused Linux gnome-keyring dependency/runtime checks and secure-store probe
cdx keyring install Install Linux keyring dependencies on Debian/Ubuntu/Mint (--yes, --skip-check)
cdx usage Show usage overview for all accounts
cdx usage <account> Show detailed usage for a specific account
cdx update-self Update cdx to the latest version
cdx self-update / cdx update / cdx updte Aliases for cdx update-self
cdx help [command] Show help for all commands or one command
cdx complete <shell> Generate shell completion script (zsh, bash, fish, powershell)
cdx version Show CLI version
cdx --help Show help
cdx --version Show version
cdx --secret-store legacy-keychain <command> Override configured backend for this run (macOS legacy keychain)

Tip: On SSH/VPS, prefer cdx login (without --device-flow) and complete login via manual callback URL/code copy-paste. The manual flow can offer clipboard copy assist (including OSC52 on compatible terminals) to avoid selecting long URLs. In Mosh sessions, OSC52 clipboard updates may be unreliable; if needed, use the printed fallback copy command or manual copy. Device flow can be blocked by Cloudflare challenge pages.

Shell completion

Generate and source completion scripts:

# zsh
source <(cdx complete zsh)

# bash
source <(cdx complete bash)

cdx also supports shell parse completion requests via cdx complete -- .... Completions include command names, options, --secret-store values, and account ID/label suggestions for commands like switch, relogin, usage, and label.

How It Works

Secure credential storage

  • macOS: macOS Keychain
  • Windows: Windows Credential Manager
  • Linux: Secret Service/keyring
  • Default backend selection is automatic (auto).
  • You can persist a preferred backend in accounts.json via optional "secretStore" ("auto" or "legacy-keychain").
  • --secret-store <mode> always overrides config for the current run.
  • If only a fallback secure-store backend is available on your platform, cdx asks for one-time explicit consent before the first credential write and explains the security trade-off.
    • Non-interactive override (if you accept the risk): set CDX_ALLOW_SECURE_STORE_FALLBACK=1
  • On macOS, cdx doctor --check-keychain-acl checks whether configured secrets were created for the current cdx/Bun runtime or by the legacy Apple security CLI flow. Legacy ACL entries can trigger frequent keychain password prompts; when a mismatch is detected, cdx suggests cdx migrate-secrets. This check can be slow.
  • Cross-keychain payload size policy:
    • Default max password length override is 16384.
    • Optional override: set CDX_CROSS_KEYCHAIN_MAX_PASSWORD_LENGTH=<integer-above-4096>.
    • This currently relies on @bjesuiter/cross-keychain@1.1.0-jb.0 until upstream support is released.

Account list path

  • macOS/Linux: ~/.config/cdx/accounts.json (or $XDG_CONFIG_HOME/cdx/accounts.json)
  • Windows: %APPDATA%\\cdx\\accounts.json

Auth file paths

macOS / Linux

  • OpenCode: ~/.local/share/opencode/auth.json (or $XDG_DATA_HOME/opencode/auth.json)
  • Codex CLI: ~/.codex/auth.json
  • Pi Agent: ~/.pi/agent/auth.json (or $PI_CODING_AGENT_DIR/auth.json)

Windows

  • OpenCode: %LOCALAPPDATA%\\opencode\\auth.json
  • Codex CLI: %USERPROFILE%\\.codex\\auth.json
  • Pi Agent: %USERPROFILE%\\.pi\\agent\\auth.json (or %PI_CODING_AGENT_DIR%\\auth.json)

cdx writes Codex CLI auth only when id_token exists.

For Developers

Install from source

git clone https://github.com/bjesuiter/codex-switcher.git
cd codex-switcher
bun install
bun link

Releasing a new version

  1. Increase version in package.json
  2. Add changelog entry for the version in CHANGELOG.md
  3. Commit the changes
  4. Create a git tag with the version number (no prefix): git tag X.Y.Z
  5. Push both the commit and the tag: git push && git push --tags

Manual Configuration (Advanced)

You can also manually add accounts to Keychain (macOS only):

security add-generic-password -a "ACCOUNT_ID" -s "cdx-openai-ACCOUNT_ID" -w '{"refresh":"REFRESH","access":"ACCESS","expires":1234567890,"accountId":"ACCOUNT_ID"}' -U

And create the accounts list manually:

{
  "current": 0,
  "secretStore": "auto",
  "accounts": [
    { "accountId": "ACCOUNT_ID", "keychainService": "cdx-openai-ACCOUNT_ID" }
  ]
}

Save to ~/.config/cdx/accounts.json.

About

Switch pi, codex and opencode auth between multiple openAI Plus and Pro accounts

www.npmjs.com/package/@bjesuiter/codex-switcher

Resources

Readme

License

MIT license
Activity

Stars

4 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

23 tags

Packages

 
 
 

Contributors 1

Languages
⚡