Skip to main content
The codex-multi-auth CLI provides a comprehensive set of commands for managing multiple ChatGPT accounts, monitoring health, and automating account operations.

​
Command Family

All commands use the canonical codex auth ... syntax: 
codex auth <command> [options]

​
Compatibility Aliases

The following aliases are also supported for backward compatibility:
  • codex multi auth ...
  • codex multi-auth ...
  • codex multiauth ...

​
Command Categories

​
Primary Commands

Core operations for daily account management:
CommandPurpose
codex auth loginOpen interactive auth dashboard
codex auth listList saved accounts and active account
codex auth statusPrint short runtime/account summary
codex auth switchSet active account by index
codex auth checkRun quick account health check
codex auth featuresDisplay implemented feature list

​
Advanced Commands

Diagnostics, repairs, and operational planning:
CommandPurpose
codex auth verify-flaggedVerify flagged accounts and optionally restore
codex auth forecastForecast best account by readiness/risk
codex auth reportGenerate full health report
codex auth fixApply safe account storage fixes
codex auth doctorRun diagnostics and optional repairs

​
Common Flags

Many commands share these flags:
​
--json
boolean
Output machine-readable JSON instead of human-friendly text. Available on: verify-flagged, forecast, report, fix, doctor.
​
--live
boolean
Perform live quota probes before decisions/output. Available on: forecast, report, fix.
​
--dry-run
boolean
Preview changes without writing to storage. Available on: verify-flagged, fix, doctor.
​
--model
string
default:"gpt-5-codex"
Specify model for live probe requests. Available on: forecast, report, fix.

​
Quick Start Workflows

​
First-time setup

codex auth login
codex auth check
codex auth forecast --live

​
Daily health monitoring

codex auth check
codex auth forecast --live --model gpt-5-codex

​
Repair and recovery

codex auth fix --dry-run
codex auth fix --live
codex auth doctor --fix

​
Automation-friendly workflows

codex auth report --live --json
codex auth forecast --json
codex auth verify-flagged --json

​
Exit Codes

All commands follow standard Unix exit code conventions:
  • 0 - Success
  • 1 - General error
  • 130 - Interrupted (SIGINT)

​
Storage Locations

Commands read/write these files:
  • Accounts: ~/.codex/multi-auth/openai-codex-accounts.json
  • Flagged: ~/.codex/multi-auth/openai-codex-flagged-accounts.json
  • Quota cache: ~/.codex/multi-auth/quota-cache.json
  • Settings: ~/.codex/multi-auth/settings.json
Override the root directory with CODEX_MULTI_AUTH_DIR.

Build docs developers (and LLMs) love

Get started for freeTalk to us