Codex Account Switcher

codex-account is a small cross-platform Node CLI for switching between local Codex auth snapshots.

It does not call codex logout, so it does not intentionally revoke server-side tokens. It only moves and copies local auth.json files.

Desktop Client

Prefer a graphical interface? A separate Codex Account Switcher desktop client is available for managing accounts without using terminal commands.

Download the client from GitHub Releases. This package remains the CLI tool; the desktop client is distributed separately.

Install

From this folder:

npm install -g .

From npm after publishing:

npm install -g @cyilang/codex-switch

Then run:

codex-account tutorial

To preview another OS tutorial:

codex-account tutorial --os windows
codex-account tutorial --os macos
codex-account tutorial --os linux

First-Time Setup

1. Log in to account A in Codex.
2. Capture it:

codex-account capture account-a

3. Prepare to log in to account B without using logout:

codex-account prepare-login

4. Reopen Codex, log in to account B, then capture it:

codex-account capture account-b

5. Switch whenever needed:

codex-account switch account-a
codex-account switch account-b --restart

Before switching, the CLI calls account/read with refreshToken: true so Codex proactively refreshes the current managed login, then saves the resulting auth back to its slot. If refresh is temporarily unavailable, it keeps the existing snapshot, prints a warning, and continues the switch.

Rename or delete saved account slots:

codex-account rename account-a work
codex-account delete old-account

delete only removes the saved snapshot. It does not delete the currently active Codex auth.json.

When switching away from the known current account, the tool first syncs the latest active auth.json back into that saved slot. This helps preserve refreshed or rotated tokens without requiring a manual capture every time.

Show current weekly Codex quota:

codex-account quota
codex-account quota account-a
codex-account quota --all

Commands

capture <name>              Save the current Codex login as an account slot
prepare-login               Move current auth aside so you can log in to another account
switch <name> [--restart]   Switch to a saved account; optionally restart Codex App
rename <old> <new>          Rename a saved account slot
delete <name>               Delete a saved account slot without removing current auth
quota [name|--all]          Show weekly quota for current, one saved account, or all saved accounts
list                        List saved accounts without showing tokens
current                     Show current switcher state
doctor                      Check paths, auth JSON, and storage state
tutorial [--os OS]          Show a system-specific tutorial
completion <shell>          Print shell completion for bash, zsh, fish, or powershell
help                        Show the command index

Paths

Codex auth:

• macOS/Linux: ~/.codex/auth.json
• Windows: %USERPROFILE%\.codex\auth.json
• Override: CODEX_HOME

Switcher data:

• macOS/Linux: ~/.codex-account-switcher/
• Windows: %APPDATA%\codex-account-switcher\

Restart

By default, switch only prints a reminder to restart Codex App.

Use --restart when you explicitly want the tool to close and reopen the app:

codex-account switch account-a --restart

This can interrupt active local Codex App tasks.

Quota

codex-account quota starts a short-lived local Codex app-server process and reads:

• weekly Codex limit usage
• remaining percentage
• actual reset time in your local timezone
• time until reset
• reset credits, when available
• recent token usage summary, when available

It does not print auth tokens or raw auth JSON.

If quota cannot find the codex binary, set CODEX_ACCOUNT_CODEX_PATH to the full Codex CLI path. On macOS, the tool also tries the ChatGPT/Codex app bundled binary automatically.

Quota examples:

codex-account quota          # current active auth
codex-account quota account-a
codex-account quota --all    # every saved snapshot

When reading saved snapshots, the tool copies each saved auth.json into a temporary CODEX_HOME, queries from there, then deletes the temporary directory. It does not replace your real current Codex auth while checking saved accounts.

If the quota query refreshes the temporary auth, the saved snapshot is updated with the refreshed auth so future switches keep working.

On Windows, --restart tries several launch methods after closing common ChatGPT/Codex processes:

1. CODEX_ACCOUNT_APP_COMMAND
2. CODEX_ACCOUNT_APP_PATH
3. Start Menu shortcuts
4. common install paths
5. codex app
6. Windows StartApps

If your Windows install uses a custom location, set one of these before switching:

$env:CODEX_ACCOUNT_APP_PATH = "C:\Path\To\ChatGPT.exe"
codex-account switch account-a --restart

Or with CMD:

set CODEX_ACCOUNT_APP_PATH=C:\Path\To\ChatGPT.exe
codex-account switch account-a --restart

For custom launchers, set CODEX_ACCOUNT_APP_COMMAND to a full command.

Tab Completion

Generate a completion script for your shell:

codex-account completion zsh
codex-account completion bash
codex-account completion fish
codex-account completion powershell

macOS zsh example:

codex-account completion zsh > ~/.codex-account-completion.zsh
echo 'source ~/.codex-account-completion.zsh' >> ~/.zshrc
source ~/.zshrc

Bash example:

codex-account completion bash > ~/.codex-account-completion.bash
echo 'source ~/.codex-account-completion.bash' >> ~/.bashrc

Fish example:

codex-account completion fish > ~/.config/fish/completions/codex-account.fish

PowerShell example:

codex-account completion powershell >> $PROFILE.CurrentUserAllHosts

Completion includes command names, common options, OS names for tutorial, shell names for completion, and saved account names for switch, rename, delete, and quota.

Security

The tool never prints access tokens, refresh tokens, API keys, or full auth JSON. On macOS/Linux it attempts to set account storage directories to 700 and auth snapshots to 600. On Windows it stores data under the current user's %APPDATA% and does not modify ACLs.