@minniexcode/codex-switch

@minniexcode/codex-switch is a local-first CLI for managing and switching Codex provider and model-provider routing safely.

It keeps codex-switch tool state separate from the target Codex runtime, so provider management, backup flow, and runtime projection stay explicit instead of relying on manual file edits.

Chinese version: README.CN.md

Version

Current package version: 0.1.1

This is the current stable release line. 0.1.1 aligns the public docs with the Codex 0.134.0+ runtime contract where top-level model and model_provider select the active route.

Install

npm install -g @minniexcode/codex-switch

Run without a global install:

npx @minniexcode/codex-switch --help

Built CLI entrypoint:

codexs --help

Primary Workflows

Direct provider workflow:

codexs init
codexs add my-provider --model gpt-5.5 --base-url https://gateway.example.com/v1 --api-key sk-xxx
codexs switch my-provider
codexs status
codexs doctor

GitHub Copilot workflow:

codexs init
codexs login copilot
codexs add copilot-main --copilot --model gpt-4.1
codexs switch copilot-main
codexs status
codexs doctor

Notes:

• init prepares the codex-switch tool home and managed state.
• login copilot handles upstream Copilot onboarding and auth readiness.
• add --copilot does not perform login for you; it assumes Copilot login is already ready.
• switch projects the selected provider into the target Codex runtime as top-level model plus model_provider.
• status is the main read command after switching.
• doctor is the main repair-oriented diagnostic command.

Runtime Routing Model

For Codex 0.134.0+, the active runtime route is selected through top-level model and model_provider in config.toml.

codex-switch treats that route as the runtime contract:

• top-level model selects the active model id
• top-level model_provider selects the active provider route
• managed [model_providers.<id>] entries are the projected runtime provider definitions
• --profile is only an alias for the managed model_provider id, not the primary runtime selector

Direct-provider projection writes:

• top-level model
• top-level model_provider
• [model_providers.<id>]
• auth.json with OPENAI_API_KEY

Managed direct-provider projection does not keep env_key or env_key_instructions in the generated runtime config. switch, add, and edit clean old legacy projection fields before writing the active route.

For managed OpenAI-compatible routes, the projected provider entry keeps the fixed runtime shape:

model = "gpt-5.5"
model_provider = "my-provider"

[model_providers.my-provider]
name = "my-provider"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

Advanced Adopt Workflow

Use migrate only when you already have Codex runtime state that should be adopted into managed providers.json state:

codexs init
codexs migrate

migrate is an advanced adopt helper. It is not the default first step for a fresh install.

Command Surface

codexs init
codexs login copilot
codexs migrate
codexs list
codexs show <provider>
codexs current
codexs status
codexs config show [profile]
codexs config list-profiles
codexs add <provider> --model <model> --api-key <key> [--base-url <url>]
codexs add <provider> --copilot --model <model>
codexs edit <provider>
codexs switch <provider>
codexs remove <provider> [--force] [--switch-to <provider>]
codexs import <file>
codexs export <file> [--force]
codexs bridge start [provider]
codexs bridge status [provider]
codexs bridge stop [provider]
codexs backups list
codexs rollback [backup-id]
codexs doctor

setup still exists only as a deprecated compatibility entry that points callers to init or migrate.

Runtime Model

Tool home:

~/.config/codex-switch/
  codex-switch.json
  providers.json
  backups/
  runtime/
  runtimes/

Target Codex runtime:

~/.codex/
  config.toml
  auth.json

Key points:

• providers.json is the managed provider registry and lives under the tool home.
• codex-switch.json stores tool-level metadata such as defaultCodexDir.
• config.toml remains the active runtime routing file in the target Codex directory.
• auth.json remains the active auth projection file in the target Codex directory.
• Direct providers rewrite OPENAI_API_KEY into the active runtime projection.
• Copilot providers keep upstream GitHub authentication in the official Copilot runtime while codex-switch manages local bridge state and routing.

Path controls:

• --codex-dir <path> targets a specific Codex runtime directory.
• CODEXS_CODEX_DIR provides the default target runtime when --codex-dir is not passed.
• CODEXS_HOME overrides the tool home location.

Automation Notes

This CLI supports both human TTY usage and non-interactive automation.

Global flags:

--json
--codex-dir <path>
--help
--version

Operational limits:

• login copilot requires a real TTY and does not support --json.
• migrate remains interactive when provider adoption requires human input.
• Automation should pass explicit arguments and prefer --json for stable parsing.

Local Development

npm run build
npm test
npx tsc --noEmit
node dist/cli.js --help
npm pack --dry-run

Documentation

• Chinese README
• AI README
• Detailed CLI Usage
• Testing Guide
• Product Overview
• Release PRD 0.1.1
• Release Design 0.1.1

License

MIT