Skip to main content
This guide walks you through adding your first account, verifying the setup, and running essential health checks.

​
Add your first account

1

Open the account dashboard

Launch the interactive account management dashboard:
codex auth login
The dashboard will open in your terminal with a list of saved accounts (empty on first run).
2

Add a new account

In the dashboard:
  1. Select Add New Account using arrow keys and press Enter
  2. Your browser will open to the ChatGPT OAuth consent page
  3. Approve the authorization request
  4. Return to your terminal
The OAuth callback runs on http://127.0.0.1:1455/auth/callback. Ensure port 1455 is available.
3

Verify account storage

List your saved accounts to confirm the new account was added:
codex auth list
You should see output showing your newly added account marked as active:
Saved Accounts:
→ [1] [email protected] (active)
4

Run a health check

Verify the account is healthy and ready to use:
codex auth check
This performs a quick health assessment of all configured accounts.

​
Add additional accounts

For multi-account rotation and failover, add more accounts:
1

Repeat the login flow

Open the dashboard again and add another account:
codex auth login
Select Add New Account and complete OAuth for a different ChatGPT account.
2

Forecast account health

Run a live forecast to see which account will be selected for the next request:
codex auth forecast --live
The --live flag performs real-time health probes against the ChatGPT backend.

​
Essential commands

Now that you have accounts configured, try these day-1 commands: 
codex auth list

​
Dashboard hotkeys

When you’re in the interactive dashboard (codex auth login), use these keyboard shortcuts:

​
Main dashboard

KeyAction
Up / DownMove selection
EnterSelect/open
1-9Quick switch to account by number
/Search accounts
?Toggle help
QBack/cancel

​
Account details

KeyAction
SSet as current account
RRefresh/re-login account
EEnable/disable account
DDelete account

​
Verify your setup

Run this full verification sequence to ensure everything is working: 
# Check plugin status
codex auth status

# List all accounts
codex auth list

# Health check all accounts
codex auth check

# Verify flagged accounts (if any)
codex auth verify-flagged --json

# Live forecast for next request
codex auth forecast --live

# Preview any recommended fixes
codex auth fix --dry-run

# Generate full health report
codex auth report --live --json

# Run diagnostics
codex auth doctor --json
The --json flag outputs machine-readable JSON instead of human-friendly terminal output. Useful for automation and logging.

​
Common first-run issues

If codex auth is not recognized:
# Check where the codex binary is installed
where codex  # Windows
which codex  # Unix/macOS

# Try compatibility aliases
codex multi auth status
codex multi-auth status
codex multiauth status
If none work, verify your global npm installation path is in your PATH environment variable.
The OAuth server binds to 127.0.0.1:1455. If you see port binding errors:
# Find and stop the process using port 1455
# Unix/macOS:
lsof -ti:1455 | xargs kill

# Windows:
netstat -ano | findstr :1455
# Then kill the PID shown
After freeing the port, retry codex auth login.
If codex auth switch <index> completes but the wrong account appears active:
  1. Run the switch command again: 
    codex auth switch 1
  2. Restart your terminal session
  3. Verify with: 
    codex auth list
If you see OAuth token errors:
# Re-login the affected account
codex auth login
# Select the account and choose "Refresh/re-login"
Or delete and re-add the account:
codex auth login
# Select the account and choose "Delete account"
# Then add it again with "Add New Account"
If account data appears stale:
# Run automatic diagnostics and fixes
codex auth doctor --fix

# Then verify
codex auth check
codex auth forecast --live

​
60-second recovery

If anything goes wrong, run this recovery sequence: 
codex auth doctor --fix
codex auth check
codex auth forecast --live
If issues persist: 
codex auth login
# Delete and re-add problematic accounts

​
Storage locations

Codex Multi-Auth stores configuration and account data in these locations:
FileDefault path
Settings~/.codex/multi-auth/settings.json
Accounts (global)~/.codex/multi-auth/openai-codex-accounts.json
Accounts (per-project)~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json
Flagged accounts~/.codex/multi-auth/openai-codex-flagged-accounts.json
Quota cache~/.codex/multi-auth/quota-cache.json
Logs~/.codex/multi-auth/logs/codex-plugin/
You can override the root directory with the CODEX_MULTI_AUTH_DIR environment variable.

​
Next steps

Features

Explore advanced features like project-scoped accounts and session affinity

Configuration

Customize settings and environment variables

Commands reference

Complete reference for all codex auth commands

Troubleshooting

Detailed troubleshooting guide for common issues

Build docs developers (and LLMs) love

Get started for freeTalk to us