Open the interactive terminal dashboard for managing accounts, running diagnostics, and configuring settings.
Usage
This command launches the full-screen TUI (terminal user interface) dashboard.
What It Does
- Launches OAuth flow - Opens your browser to sign in with ChatGPT
- Manages existing accounts - View, switch, refresh, or delete accounts
- Health monitoring - Real-time quota and session status
- Settings configuration - Interactive settings editor
- Account deduplication - Automatically merges accounts by token/email/ID
Dashboard Hotkeys
Main Dashboard
| Key | Action |
|---|
Up / Down | Move selection |
Enter | Select/open |
1-9 | Quick switch to visible account |
/ | Search accounts |
? | Toggle help panel |
Q | Back/cancel |
Account Details
| Key | Action |
|---|
S | Set as current account |
R | Refresh/re-login account |
E | Enable/disable account |
D | Delete account |
Q | Back to main menu |
Settings Screens
| Key | Action |
|---|
Enter | Toggle/select option |
1-9 | Quick toggle numbered options |
S | Save changes |
R | Reset to defaults |
Q | Cancel without saving |
[ / ] | Reorder summary fields |
+ / - | Adjust numeric settings |
OAuth Flow Modes
Browser Mode (Default)
The CLI attempts to open your default browser automatically:
◆ Choose sign-in mode:
○ Open browser and sign in
○ Copy URL and paste callback manually
○ Back/cancel
Manual Mode
If browser launch fails or you prefer manual control:
- Select “Copy URL and paste callback manually”
- The OAuth URL is copied to your clipboard
- Open the URL in any browser
- Complete the sign-in flow
- Copy the callback URL from the success page
- Paste it back in the terminal
The CLI accepts these callback formats:
- Full URL:
http://127.0.0.1:1455/auth/callback?code=...&state=...
- Just the code:
abc123...
- Query string:
?code=abc123&state=xyz
Account Deduplication
When you log in with an existing account, it’s automatically merged by:
- Refresh token (highest priority)
- Account ID (from JWT)
- Email address (case-insensitive)
This prevents duplicate entries and preserves:
- Last used timestamp
- Custom account labels
- Health scores
- Rate limit tracking
Examples
First-time login
codex auth login
# Opens dashboard → select "Add account" → OAuth flow
Add another account
codex auth login
# Opens dashboard → select "Add account" → force new login
Refresh existing account
codex auth login
# Opens dashboard → select account → press R
OAuth Callback Server
The CLI starts a local HTTP server on http://127.0.0.1:1455 to receive OAuth callbacks.
Fixed port for OAuth callbacks. Cannot be changed (hardcoded in ChatGPT OAuth app registration).
Troubleshooting Port Conflicts
If port 1455 is already in use:
# Linux/macOS: Find process using port 1455
lsof -i :1455
# Windows: Find process using port 1455
netstat -ano | findstr :1455
# Kill the process or use manual callback mode
Interactive Settings
From the main dashboard, select “Settings” to configure:
- Display settings - Menu layout, colors, status badges
- Summary settings - Visible columns, sort order
- Behavior settings - Auto-refresh, session affinity
- Theme settings - Color scheme, glyphs, contrast
All changes are saved to ~/.codex/multi-auth/settings.json.
Press Q in settings to cancel without saving. Theme previews automatically restore on cancel.
Error Handling
Missing Browser
! Could not open browser automatically
→ Go to: https://chatgpt.com/oauth/authorize?...
✓ URL copied to clipboard
OAuth Callback Timeout
! OAuth callback not received in time
→ Paste the callback URL or code manually:
Token Exchange Failed
✗ Token exchange failed: invalid_grant
Storage Impact
This command writes to:
~/.codex/multi-auth/openai-codex-accounts.json - Account pool~/.codex/multi-auth/settings.json - Dashboard preferences~/.codex/cli/state.json - Active account sync (Codex CLI)
Backups are created with .backup suffix before destructive operations.