codex-switch

Manage multiple OpenAI Codex CLI accounts from the command line.

If you use multiple ChatGPT Pro/Plus subscriptions for Codex CLI — for parallel batch evaluation, team usage, or quota management — this tool lets you switch between accounts, check real-time quota, and validate token health without manually copying auth.json files.

Install

# With uv (recommended)
uv tool install codex-switch

# Or with pip
pip install codex-switch

Requires Python 3.11+ and Codex CLI installed.

Quick Start

# Save your current logged-in account
codex-switch save work

# Import another auth.json
codex-switch add ~/Downloads/auth.json personal

# See all accounts at a glance
codex-switch list

# Switch to a different account
codex-switch switch personal

Commands

codex-switch list

Show all saved accounts with plan, quota, token expiry, and live API status:

Saved Codex accounts
   name      email                         plan  quota                                         access_exp   live
-  --------  ----------------------------  ----  --------------------------------------------  -----------  ----
*  pro1      user1@example.com             pro   5h:69% (04-03 19:52) / wk:55% (04-10 00:34)  04-10 10:48  ok
   pro2      user2@example.com             pro   5h:0% (04-03 23:05) / wk:6% (04-10 18:05)    04-13 16:27  ok
   personal  user3@gmail.com               pro   5h:0% (04-03 23:05) / wk:0% (04-10 18:05)    04-13 16:18  ok

• * = currently active account (matches ~/.codex/auth.json)
• 5h = 5-hour rolling window usage and reset time, wk = 7-day rolling window usage and reset time
• access_exp = when the access token expires (local time)
• live = real-time API validation result

codex-switch switch <name>

Switch the active Codex CLI account:

$ codex-switch switch pro2
Switched to account 'pro2'
Active auth: /home/user/.codex/auth.json

codex-switch quota [name]

Check real-time quota for the current or a specific account. Does not consume any API quota:

$ codex-switch quota pro1
Quota for pro1
email: user1@example.com
plan:  pro
auth:  chatgpt

bucket           name                 5h                 week               credits  plan
---------------  -------------------  -----------------  -----------------  -------  ----
codex            -                    70% (04-03 19:52)  55% (04-10 00:34)  0        pro
codex_bengalfox  GPT-5.3-Codex-Spark  0% (04-03 23:05)   0% (04-10 18:05)   -        pro

codex-switch refresh [name]

Refresh access tokens for the current or a named account. Does not consume API quota:

$ codex-switch refresh pro1
Refreshed pro1
email: user1@example.com
plan:  pro
access token: ok (2026-04-22 06:01Z)
id token:     ok (2026-04-12 07:01Z)

Updated files:
  /home/user/.codex-switch/pro1.json
  /home/user/.codex/auth.json

• If the refreshed account is the currently active account, ~/.codex/auth.json is also updated
• Without a name, refreshes ~/.codex/auth.json directly and syncs back to the matching saved account

codex-switch probe [name]

Run a tiny Codex request for the current or a named account. This is useful when you want to start the account's rolling quota window before checking list or quota.

$ codex-switch probe pro1
Probing pro1
auth:  /home/user/.codex-switch/pro1.json
model: Codex CLI default
Probe completed
reply: OK
email: user1@example.com
plan:  pro
quota: 5h:1% (04-03 19:52) / wk:1% (04-10 00:34)

Use --model when you need to start usage for a specific model bucket:

codex-switch probe pro1 --model gpt-5.1-codex

Unlike quota, this command sends one real Codex request and can consume a small amount of quota. It uses a temporary CODEX_HOME, so it does not switch or rewrite your active ~/.codex/auth.json.

codex-switch validate [name]

Check token health for one account or all saved accounts:

$ codex-switch validate pro2
pro2
  email:   user2@example.com
  plan:    pro
  access:  ok (2026-04-13 08:27)
  id:      expired (2026-04-03 09:27)
  refresh: present
  live:    OK 5h:0% / wk:6%

codex-switch current

Show details about the currently active account:

$ codex-switch current
Current Codex account
name:  pro1
path:  /home/user/.codex/auth.json
email: user1@example.com
plan:  pro
access token: ok (2026-04-10 02:48)
id token:     expired (2026-03-31 03:48)
refresh:      present

codex-switch save <name>

Save the current ~/.codex/auth.json as a named account:

$ codex-switch save work
Saved current auth as 'work'

codex-switch add <path> <name>

Import an auth.json file as a named account:

$ codex-switch add ~/Downloads/auth.json team-account
Imported account 'team-account'

codex-switch remove <name> (alias: rm)

Remove a saved account. Cannot remove the currently active account:

$ codex-switch remove old-account
Removed account 'old-account'

codex-switch rename <old> <new> (alias: mv)

Rename a saved account:

$ codex-switch rename team-account team
Renamed 'team-account' → 'team'

How it works

Codex CLI stores authentication in ~/.codex/auth.json. This tool maintains named copies in ~/.codex-switch/ and swaps them when you switch accounts.

Quota checking starts a temporary codex app-server process pointed at the target account, queries the account/rateLimits/read JSON-RPC endpoint, and shuts down. No Codex API quota is consumed.

Storage layout

~/.codex-switch/
├── pro1.json        # saved auth.json for "pro1"
├── pro2.json        # saved auth.json for "pro2"

Environment variables

For testing or custom setups:

• CODEX_SWITCH_DATA_DIR — override the account storage directory (default: ~/.codex-switch)
• CODEX_SWITCH_CODEX_HOME — override the Codex home directory (default: ~/.codex)

License

MIT