codex-auth is a command-line tool for switching Codex accounts and provider profiles discovered from ~/.codex/config.toml.

codex-auth works with these Codex clients:

• Codex CLI
• VS Code extension
• Codex App

For the best experience, install the Codex CLI even if you mainly use the VS Code extension or the App, because it makes adding accounts easier:

npm install -g @openai/codex

After that, you can use codex login, codex login --device-auth, codex-auth login, or codex-auth login --device-auth to sign in and add accounts more easily.

Install with npm:

npm install -g @loongphy/codex-auth

You can also run it without a global install:

npx @loongphy/codex-auth list

npm packages currently support Linux x64, macOS x64, macOS arm64, Windows x64, and Windows arm64.

If you are working from a local checkout and want a one-command rebuild/install of the current branch:

bash scripts/source-install.sh

If ~/.local/bin is not already on your current PATH, use:

source scripts/source-install.sh

That version installs Zig automatically if it is missing, builds the current source tree, installs codex-auth into ~/.local/bin, updates your shell profile for future shells, and also makes the command available immediately in the current shell.

If Zig is already installed and you only want the bare source build/install step, you can still run:

bash scripts/dev-install.sh

Remove the npm package:

npm uninstall -g @loongphy/codex-auth

For non-npm installs on Linux/macOS/WSL2 only:

rm -f ~/.local/bin/codex-auth
rm -f ~/.local/bin/codex-auth-auto
sed -i '/# Added by codex-auth installer/,+1d' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc ~/.zprofile 2>/dev/null || true

If you used fish, also remove the old profile entry:

sed -i '/# Added by codex-auth installer/,+3d' ~/.config/fish/config.fish 2>/dev/null || true

For non-npm installs on Windows only:

Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth-auto.exe" -Force -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable(
  "Path",
  (($env:Path -split ';' | Where-Object { $_ -and $_ -ne "$env:LOCALAPPDATA\codex-auth\bin" }) -join ';'),
  "User"
)

codex-auth list

When codex-auth config list enable is on, list refreshes every account's usage via the API before rendering and stores the refreshed snapshots in registry.json. Later switch commands reuse that cached usage data in the picker. Provider profiles are scanned from ~/.codex/config.toml on each list and shown in the same table with PLAN=provider and - usage cells.

Interactive: shows accounts and provider profiles in one picker.

codex-auth switch

Before the picker opens, the current active account's usage is refreshed once so the selected row is not stale. If the active target is a provider profile, auth sync is skipped and ~/.codex/config.toml remains authoritative.

Non-interactive: fuzzy match by email, alias, provider label, or provider id.

codex-auth switch john             # match any account containing "john"
codex-auth switch john@gmail.com   # match by full or partial email
codex-auth switch work             # match by alias set during import
codex-auth switch openrouter       # match a scanned provider profile

If the keyword matches multiple targets, the command falls back to interactive selection. Press q to quit without switching.

codex-auth remove

remove only deletes stored accounts. Provider profiles stay in ~/.codex/config.toml; edit that file directly if you want to add, change, or remove them.

Add provider blocks directly to ~/.codex/config.toml. codex-auth scans [model_providers.<id>] entries on each list, switch, and provider list.

# ~/.codex/config.toml
model_provider = "openrouter"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
wire_api = "responses"
experimental_bearer_token = "sk-test"

# then inspect or switch to it
codex-auth provider list
codex-auth switch openrouter

Add the currently logged-in Codex account:

codex-auth login
codex-auth login --device-auth

codex-auth import /path/to/auth.json --alias personal

Scans all .json files in the directory:

codex-auth import /path/to/auth-exports

Typical output:

Scanning /path/to/auth-exports...
  ✓ imported  token_ryan.taylor.alpha@email.com
  ✓ updated   token_jane.smith.alpha@email.com
  ✗ skipped   token_invalid: MalformedJson
Import Summary: 1 imported, 1 updated, 1 skipped (total 3 files)

stdout carries scanning, success, and summary lines. Skipped files and warnings stay on stderr.

CLIProxyAPI stores tokens as flat JSON under ~/.cli-proxy-api/. Import them directly without conversion:

codex-auth import --cpa                                  # scan default ~/.cli-proxy-api/*.json
codex-auth import --cpa /path/to/cpa-dir                 # scan a specific directory
codex-auth import --cpa /path/to/token.json --alias bob  # import a single CPA file

If codex-auth list shows missing accounts or wrong usage data, the internal registry file may be out of sync with the actual auth files on disk. This command re-reads all auth files and rebuilds the registry from scratch:

codex-auth import --purge                                # rebuild from ~/.codex/accounts/*.auth.json
codex-auth import --purge /path/to/auth-exports          # rebuild from a specific folder

This does not import new files. It repairs the registry index for auth snapshots that already exist on disk.

codex-auth status

Enable or disable:

codex-auth config auto enable
codex-auth config auto disable

config auto enable prints the current usage mode after installing the watcher, so you can immediately see whether auto-switch is running with default API-backed usage or local-only fallback semantics.

Adjust thresholds:

codex-auth config auto --5h 12
codex-auth config auto --5h 12 --weekly 8
codex-auth config auto --weekly 8

When auto-switching is enabled, a long-running background watcher refreshes the active account's usage and silently switches accounts when:

• 5h remaining drops below the configured 5h threshold (default 10%), or
• weekly remaining drops below the configured weekly threshold (default 5%)

The managed background worker is long-running on all supported platforms:

• Linux/WSL: persistent systemd --user service
• macOS: LaunchAgent
• Windows: scheduled task that launches the long-running helper at logon, restarts it after failures, has no 72-hour execution cap, and also starts it immediately on enable

API-backed fallback:

codex-auth config api enable

Local-only, no usage API calls:

codex-auth config api disable

Changing config api updates registry.json immediately. api enable is shown as API mode and api disable is shown as local mode.

Refresh every account during list:

codex-auth config list enable
codex-auth config list disable

When enabled, each list call refreshes usage for every stored account snapshot before printing the table. Accounts that fail to refresh keep their previous cached usage and print a warning.

If codex-auth is using local-only usage refresh, it reads the newest ~/.codex/sessions/**/rollout-*.jsonl file. Recent Codex builds often write token_count events with rate_limits: null. The local files may still contain older usable usage limit data, but in practice they can lag by several hours, so local-only refresh may show a usage limit snapshot from hours ago instead of your latest state.

• Upstream Codex issue: openai/codex#14880

You can switch usage limit refresh to the usage API with:

codex-auth config api enable

Then confirm the current mode with:

codex-auth status

status should show usage: api.

Upgrade notes:

• If you are upgrading from v0.1.x to the latest v0.2.x, API usage refresh is enabled by default.
• If you previously used an early v0.2 prerelease/test build and status still shows usage: local, run codex-auth config api enable once to switch back to API mode.

Verify with:

codex exec "say hello"

This project is provided as-is and use is at your own risk.

Usage Data Refresh Source: codex-auth supports two sources for refreshing account usage/usage limit information:

1. API (default): When config api enable is on, the tool makes direct HTTPS requests to OpenAI's endpoints using your account's access token. This enables both usage refresh and team name refresh.
2. Local-only: When config api disable is on, the tool scans local ~/.codex/sessions/*/rollout-*.jsonl files for usage data and skips team name refresh API calls. This mode is safer, but it can be less accurate because recent Codex rollout files often contain rate_limits: null, so the latest local usage limit data may lag by several hours.

API Call Declaration: By enabling API(codex-auth config api enable), this tool will send your ChatGPT access token to OpenAI's servers, including https://chatgpt.com/backend-api/wham/usage for usage limit and https://chatgpt.com/backend-api/accounts/check/v4-2023-04-27 for team name. This behavior may be detected by OpenAI and could violate their terms of service, potentially leading to account suspension or other risks. The decision to use this feature and any resulting consequences are entirely yours.