[!CAUTION] This project uses OAuth account credentials and is intended for personal development use.

By using this package, you acknowledge:

• This is an independent open-source project, not an official OpenAI product
• You are responsible for your own usage and policy compliance
• For production/commercial workloads, use the OpenAI Platform API

Installation

Option A: Standard install

npm i -g codex-multi-auth

Option B: Migrate from legacy scoped prerelease

npm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-auth

Option C: Verify wiring

codex --version confirms the official Codex CLI is reachable. codex-multi-auth --version confirms the installed wrapper package version.

codex --version
codex-multi-auth --version
codex auth status

Any official install path is fine as long as codex is on PATH: npm i -g @openai/codex, brew install --cask codex, or an official release binary.

Step-by-step

1. Install global package:
   • npm i -g codex-multi-auth
2. Run first login flow with codex auth login
3. Validate state with codex auth status and codex auth check
4. Confirm routing with codex auth forecast --live

Verification

codex auth status
codex auth check

Quick Start

Install and sign in:

npm i -g @openai/codex
npm i -g codex-multi-auth
codex auth login

If you already installed the official native CLI via Homebrew or a release binary, you only need:

npm i -g codex-multi-auth
codex auth login

Verify the wrapper and the new account:

codex auth status
codex auth check

Use these next:

codex auth list
codex auth switch 2
codex auth forecast --live

If browser launch is blocked, use the alternate login paths in docs/getting-started.md. For remote or headless shells, prefer codex auth login --device-auth.

Command Toolkit

Start here

| Command | What it answers | | --- | --- | | codex auth login | How do I add or re-open the account menu? | | codex auth status | Is the wrapper active right now? | | codex auth check | Do my saved accounts look healthy? |

Daily use

| Command | What it answers | | --- | --- | | codex auth list | Which accounts are saved and which one is active? | | codex auth switch <index> | How do I move to a different saved account? | | codex auth forecast --live | Which account looks best for the next session? |

Repair

| Command | What it answers | | --- | --- | | codex auth verify-flagged | Can any previously flagged account be restored? | | codex auth verify --paths | Do my storage path chain and sandbox probes still pass self-test? | | codex auth fix --dry-run | What safe storage or account repairs are available? | | codex auth doctor --fix | Can the CLI diagnose and apply the safest fixes now? |

Advanced

| Command | What it answers | | --- | --- | | codex auth report --live --json | How do I get the full machine-readable health report? | | codex auth fix --live --model gpt-5.3-codex | How do I run live repair probes with a chosen model? | | codex auth why-selected --json | Which account does the selector pick now, and why? | | codex auth usage --since 24h --by project | What local usage has been recorded recently? | | codex auth monitor --json | What is the combined usage, policy, quota, runtime, and project state? | | codex auth bridge token create --label local-client | How do I create a local bridge bearer token? | | codex auth integrations --kind python | How do I generate local bridge client snippets? | | codex auth rotation status | Is live runtime account rotation enabled for forwarded Codex sessions? |

Reliability behavior

• whole-pool replay is disabled by default when every account is rate-limited
• active requests use a bounded outbound request budget so one prompt cannot walk the full pool indefinitely
• repeated cross-account 5xx bursts trigger a short cooldown instead of continuing aggressive rotation
• proactive refresh is staggered to reduce background refresh bursts
• codex auth status surfaces recent runtime request metrics in text output, and codex auth report --json exposes the machine-readable cooldown/runtime snapshot

Dashboard Hotkeys

Main dashboard

| Key | Action | | --- | --- | | Up / Down | Move selection | | Enter | Select/open | | 1-9 | Quick switch | | / | Search | | ? | Toggle help | | Q | Back/cancel |

Account details

| Key | Action | | --- | --- | | S | Set current account | | R | Refresh/re-login account | | E | Enable/disable account | | D | Delete account |

Storage Paths

| File | Default path | | --- | --- | | Settings | ~/.codex/multi-auth/settings.json | | Accounts | ~/.codex/multi-auth/openai-codex-accounts.json | | Flagged accounts | ~/.codex/multi-auth/openai-codex-flagged-accounts.json | | Quota cache | ~/.codex/multi-auth/quota-cache.json | | Runtime observability | ~/.codex/multi-auth/runtime-observability.json | | Usage ledger | ~/.codex/multi-auth/usage/usage-ledger.jsonl | | Account policies | ~/.codex/multi-auth/account-policies.json | | Routing profiles | ~/.codex/multi-auth/routing-profiles.json | | Budget guards | ~/.codex/multi-auth/budget-guards.json | | Local client tokens | ~/.codex/multi-auth/local-client-tokens.json | | Runtime app helper status | ~/.codex/multi-auth/runtime-rotation-app-helper.json | | Persistent app bind state/logs | ~/.codex/multi-auth/app-bind/ | | Logs | ~/.codex/multi-auth/logs/codex-plugin/ | | Per-project accounts | ~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json |

Override root with CODEX_MULTI_AUTH_DIR=<path>.

Configuration

Primary config root:

• ~/.codex/multi-auth/settings.json
• or CODEX_MULTI_AUTH_DIR/settings.json when custom root is set

Selected runtime/environment overrides:

| Variable | Effect | | --- | --- | | CODEX_MULTI_AUTH_DIR | Override settings/accounts root | | CODEX_MULTI_AUTH_CONFIG_PATH | Alternate config file path | | CODEX_MODE=0/1 | Disable/enable Codex mode | | CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1 | Opt out/in of live Responses proxy rotation for forwarded Codex CLI/app sessions | | CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS=<ms> | Override automatic Codex app helper idle shutdown | | CODEX_MULTI_AUTH_APP_BIND_INSTALL=0/1 | Opt out/in of packaged Codex app bind self-heal during install/update or rotation enable | | CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0/1 | Opt out/in of routing supported app shortcuts during install/update or rotation enable | | CODEX_MULTI_AUTH_AUTO_UPDATE=0/1 | Opt out/in of best-effort global package auto-update checks | | CODEX_TUI_V2=0/1 | Disable/enable TUI v2 | | CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16 | TUI color profile | | CODEX_TUI_GLYPHS=ascii|unicode|auto | TUI glyph style | | CODEX_AUTH_BACKGROUND_RESPONSES=0/1 | Opt in/out of stateful Responses background: true compatibility | | CODEX_AUTH_FETCH_TIMEOUT_MS=<ms> | Request timeout override | | CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms> | Stream stall timeout override |

Validate config after changes:

codex auth