Codex Switch

Switch local Codex auth profiles without re-login churn.

codex-switch is a small shell CLI for people who use Codex with more than one authentication mode: ChatGPT subscription login, OpenAI API keys, and OpenAI-compatible third-party mirror providers.

Core Positioning

This project is a local profile switcher for Codex CLI auth state.

It is not a cloud credential manager, not a model router, and not a Homebrew-scale package manager. Its job is deliberately narrow:

• Save named snapshots of ~/.codex/auth.json.
• Save the matching Codex provider/auth settings for each profile.
• Switch profiles quickly while backing up the current active files.
• Keep private tokens out of Git by storing profiles under ~/.config/codex-switch.

The intended user is someone who already understands their Codex setup and wants a lightweight, auditable way to switch between subscription and API profiles.

What It Manages

Each profile lives locally:

~/.config/codex-switch/
  profiles/
    <name>/
      auth.json
      config.toml
  backups/

• auth.json is copied into ~/.codex/auth.json when switching.
• config.toml is merged into ~/.codex/config.toml for model_provider, preferred_auth_method, and [model_providers.*] sections.
• backups/ receives a timestamped copy of the active auth/config before every switch.

Real auth.json files contain tokens or API keys. Do not commit them.

Install

With Homebrew:

brew tap soundadam/tap
brew install codex-switch

Or clone the repo and put the script on your PATH:

git clone https://github.com/soundadam/codex-switch.git
ln -sf "$PWD/codex-switch/scripts/codex-switch" ~/.local/bin/codex-switch

Then initialize the local store:

codex-switch init

If ~/.local/bin is not on your PATH, add it in your shell config.

Quick Start

Save the current Codex login as a ChatGPT subscription profile:

codex-switch add chatgpt --profile chatgpt-subscription

Save the current Codex login as a normal OpenAI API-key profile:

codex-switch add api --profile api-key

Save a profile for an OpenAI-compatible mirror:

codex-switch add mirror --profile mirror-freedev

Switch profiles:

codex-switch switch chatgpt
codex-switch switch api
codex-switch switch mirror

Inspect local state:

codex-switch list
codex-switch status
codex-switch check chatgpt

Third-Party Mirror Templates

Templates live in templates/.

To add a mirror provider, copy templates/mirror-freedev.toml and edit:

model_provider = "my-mirror"
preferred_auth_method = "apikey"

[model_providers.my-mirror]
name = "my-mirror"
base_url = "https://example.com/v1"
wire_api = "responses"

Then save a profile with:

codex-switch add my-mirror --profile my-mirror-template

Commands

codex-switch init
codex-switch list
codex-switch status
codex-switch add <name> [source-auth.json] [--profile <template-or-config.toml>]
codex-switch import <name> [source-auth.json] [--profile <template-or-config.toml>]
codex-switch switch <name>
codex-switch use <name>
codex-switch delete <name>
codex-switch check <name>

Safety Notes

• Profiles are stored outside the repo by default: ~/.config/codex-switch.
• The repo .gitignore blocks common misplaced private files.
• Switching creates timestamped backups before changing active Codex files.
• The config merge is intentionally narrow; it does not rewrite your whole ~/.codex/config.toml.

License

MIT