Codex Auth [](https://github.com/Loongphy/codex-auth/releases/latest) [](https://github.com/Loongphy/codex-auth/releases)

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

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

Uninstall

npm

Remove the npm package:

npm uninstall -g @loongphy/codex-auth

Commands

Detailed command documentation lives in docs/commands/README.md.

Account Management

Command	Description
codex-auth list [--live] [--active] [--api|--skip-api]	List stored accounts and usage state
codex-auth login [--device-auth]	Run codex login, then add the current account
codex-auth switch [--live] [--api|--skip-api]	Switch the active account interactively
codex-auth switch <query>	Switch directly by row number or account selector
codex-auth remove [--live] [--api|--skip-api]	Remove accounts interactively
codex-auth remove <query> [<query>...]	Remove accounts by selector
codex-auth remove --all	Remove all stored accounts

Import and Maintenance

Command	Description
codex-auth import <path> [--alias <alias>]	Import a single auth file or batch import a folder
codex-auth import --cpa [<path>]	Import CLIProxyAPI token JSON
codex-auth import --purge [<path>]	Rebuild registry.json from auth files
codex-auth export [<dir>]	Export stored account auth files
codex-auth export --cpa [<dir>]	Export CLIProxyAPI token JSON
codex-auth clean	Delete managed backup and stale account files

Configuration

Command	Description
codex-auth config live --interval <seconds>	Configure live TUI refresh interval

Quick Examples

codex-auth list
codex-auth list --active
codex-auth switch
codex-auth switch 02
codex-auth remove work
codex-auth import /path/to/auth.json --alias personal
codex-auth list --skip-api

Q&A

Why is my usage limit not refreshing?

API-backed refresh is the default. When you pass --skip-api, codex-auth reads the newest ~/.codex/sessions/**/rollout-*.jsonl file instead. 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

Run the API-backed default with:

codex-auth list

Run one local-only command with:

codex-auth list --skip-api

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): 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. npm installs already satisfy the runtime requirement.
2. Local-only: With per-command --skip-api, 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 using the default API-backed refresh, 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.