Codex Auth

codex-auth is a command-line tool for switching Codex accounts.

Important

For Codex CLI users, after switching accounts, you must fully exit codex (type /exit or close the terminal session) and start it again for the new account to take effect.

If you want seamless automatic account switching without restarting codex, use forked codext, but you need to build it yourself because there is no prebuilt install method yet.

Supported Platforms

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

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, and Windows x64.

Note

If you only installed @loongphy/codex-auth with npm, you do not need any legacy cleanup steps. Older Bash/PowerShell GitHub-release installs could leave a standalone codex-auth binary outside npm's install path. If you previously used those legacy installers, remove the leftover binaries and profile changes during migration.

Uninstall

npm

Remove the npm package:

npm uninstall -g @loongphy/codex-auth

Legacy Bash Installer

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

Legacy PowerShell Installer

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"
)

Commands

Account Management

Command	Description
codex-auth list	List all accounts
codex-auth login [--device-auth]	Run codex login (optionally with --device-auth), then add the current account
codex-auth switch [<email>]	Switch active account interactively or by partial match
codex-auth remove	Remove accounts with interactive multi-select
codex-auth status	Show auto-switch, service, and usage status

Import

Command	Description
codex-auth import <path> [--alias <alias>]	Import a single file or batch import from a folder
codex-auth import --cpa [<path>]	Import CLIProxyAPI (CPA) token JSON
codex-auth import --purge [<path>]	Rebuild registry.json from existing auth files

Configuration

Command	Description
codex-auth config auto enable|disable	Enable or disable background auto-switching
codex-auth config auto [--5h <%>] [--weekly <%>]	Set auto-switch thresholds
codex-auth config api enable|disable	Enable or disable both usage refresh and team name refresh API calls

---

Examples

List Accounts

codex-auth list

Switch Account

Interactive: shows email, 5h, weekly, and last activity.

codex-auth switch

Before the picker opens, the current active account's usage is refreshed once so the selected row is not stale. The newly selected account is not refreshed after the switch completes.

Non-interactive: fuzzy match by email or alias.

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

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

Remove Accounts

codex-auth remove

Login (Add Account)

Add the currently logged-in Codex account:

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

Import

Single File

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

Batch Import from a Folder

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.

Import CLIProxyAPI (CPA) Tokens

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

Fix Broken Account Data (Rebuild Registry)

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.

Show Status

codex-auth status

Config

Auto-Switch

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

Usage Refresh Source

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.

Q&A

Why is my usage limit not refreshing?

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"

Disclaimer

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.