@typedarray/codex-switch

Manage multiple Codex authentication profiles stored under ~/.codex/profiles.

Install

npm install --global @typedarray/codex-switch

Save profiles

Sign in through the official Codex browser login and save the resulting profile:

codex-switch login

If browser callbacks are unavailable, use device authentication:

codex-switch login --device-auth

You can also save the active ~/.codex/auth.json, or pass an auth JSON object directly:

codex-switch save
codex-switch save '{"auth_mode":"chatgpt","tokens":{...}}'

Treat auth JSON as a password: it contains access credentials. Do not commit or share it.

Saved profiles are read and written only with the original nested layout: ~/.codex/profiles/<email>/<accountId>.json. Root-level profile JSON files are not treated as saved profiles. Unrecognized layouts are ignored and left unchanged.

List and switch profiles

codex-switch list
codex-switch 3
codex-switch switch [email protected]
codex-switch select

A selector can be the number shown by list, a profile key, an account ID prefix, or an account email.

list/ls separates profiles with blank lines. When reset credits are available, the final detail line shows the credit count and the nearest expiration as relative time.

After a successful switch, codex-switch restarts ChatGPT/Codex by default so the running desktop app reloads the new auth.json. To switch the file without restarting:

codex-switch 3 --no-restart
codex-switch switch [email protected] --no-restart
codex-switch select --no-restart

You can restart separately at any time:

codex-switch restart

Ping accounts

Send one minimal, non-interactive prompt with the currently active account:

codex-switch ping

The fixed prompt asks Codex to reply with pong. To ping one saved profile without switching to it, pass any selector accepted by switch, including its list number:

codex-switch ping 3
codex-switch ping [email protected]

Ping every saved profile sequentially with --all (or -a). A failed profile is reported and skipped so the remaining profiles still run:

codex-switch ping --all
codex-switch ping -a --json

Batch ping uses a temporary private Codex home for each saved profile and does not change the currently active profile.

This is useful when you want to start an unused account's weekly usage window ahead of time. The reset schedule itself is controlled by Codex; run codex-switch list afterward to check the reported reset time.

Commands

codex-switch                              List saved profiles
codex-switch <profile> [--no-restart]     Switch and restart ChatGPT/Codex
codex-switch select [--no-restart]        Select interactively, switch, and restart
codex-switch list [--json]                List saved profiles
codex-switch current [--json]             Show the active profile
codex-switch save [auth-json] [--json]    Save a profile
codex-switch switch <profile> [--no-restart] [--json]
                                          Switch profiles
codex-switch login [--device-auth]        Log in and save without switching
codex-switch ping [profile] [--json]      Ping the active or selected account
codex-switch ping --all [--json]         Ping all accounts; skip failures
codex-switch refresh <profile> [--json]   Refresh a profile token
codex-switch reset <profile> [--json]     Consume a reset credit
codex-switch delete <profile> [--json]    Delete a profile
codex-switch doctor [--json]              Show diagnostics
codex-switch restart                      Restart ChatGPT/Codex

Options:

--no-restart          Do not restart ChatGPT/Codex after switching
-a, --all             Ping every saved profile; skip failures
--codex-home <path>   Use a Codex home other than ~/.codex
-i, --interactive     Select a profile interactively
--json                Print machine-readable JSON
-h, --help            Show help
-v, --version         Show version