codex auth fix - Codex Multi-Auth

Automatically detect and fix common issues with account storage, metadata, and configuration.

Usage

codex auth fix [--dry-run] [--json] [--live] [--model <model>]

--dry-run

boolean

default:"false"

Preview repairs without making changes to storage.

--json

boolean

default:"false"

Output machine-readable JSON instead of human-friendly text.

--live

boolean

default:"false"

Perform live quota probes before applying fixes.

--model

string

default:"gpt-5-codex"

Model to use for live quota probes (only with --live).

What Gets Fixed

Automatic Repairs

Missing account IDs - Extract from JWT access tokens
Missing emails - Extract from ID tokens
Duplicate accounts - Merge by token/email/ID
Invalid active index - Reset to valid range
Corrupted metadata - Remove invalid fields
Stale access tokens - Refresh if needed
Missing timestamps - Set defaults (addedAt, lastUsed)
Invalid cooldown timers - Clear expired cooldowns
Orphaned rate limits - Remove stale entries
Storage format migration - Upgrade V1/V2 to V3

Safe Operations Only

The fix command only performs non-destructive operations:

✅ Add missing metadata
✅ Refresh expired tokens
✅ Merge duplicates
✅ Reset invalid indices
✅ Clear expired timers
❌ Delete accounts
❌ Disable accounts
❌ Change active account

Example Output

Default Mode

Running safe account fixes...
  ✓ Refreshed 2 expired access tokens
  ✓ Added missing account IDs for 1 account
  ✓ Merged 2 duplicate accounts
  ✓ Cleared 1 expired cooldown timer
  ✓ Reset invalid active index (was 99, now 0)

Result: 5 fixes applied

Dry Run Mode

Running safe account fixes (dry run)...
  ! Would refresh 2 expired access tokens
  ! Would add missing account IDs for 1 account
  ! Would merge 2 duplicate accounts
  ! Would clear 1 expired cooldown timer
  ! Would reset invalid active index (was 99, now 0)

Result (dry run): 5 fixes needed

Live Mode

Running safe account fixes with live probe (model: gpt-5-codex)...
  ✓ Probed 4 accounts for quota status
  ✓ Refreshed 2 expired access tokens
  ✓ Updated quota cache for 4 accounts
  ✓ Added missing account IDs for 1 account
  ✓ Cleared 1 expired cooldown timer

Result: 5 fixes applied (with live quota update)

JSON Output

codex auth fix --json

{
  "mode": "fix",
  "dryRun": false,
  "liveProbe": false,
  "fixes": [
    {
      "type": "refresh_token",
      "accountEmail": "[email protected]",
      "description": "Refreshed expired access token"
    },
    {
      "type": "add_account_id",
      "accountEmail": "[email protected]",
      "accountId": "user-abc123",
      "description": "Extracted account ID from access token"
    },
    {
      "type": "merge_duplicates",
      "kept": "[email protected]",
      "merged": "[email protected] (duplicate)",
      "description": "Merged duplicate account by email"
    },
    {
      "type": "clear_cooldown",
      "accountEmail": "[email protected]",
      "description": "Cleared expired cooldown timer"
    },
    {
      "type": "reset_active_index",
      "oldIndex": 99,
      "newIndex": 0,
      "description": "Reset invalid active index"
    }
  ],
  "totalFixes": 5
}

Fix Types

refresh_token

fix

Refresh expired access tokens using valid refresh tokens.

add_account_id

fix

Extract and set missing account IDs from JWT tokens.

add_email

fix

Extract and set missing email addresses from ID tokens.

merge_duplicates

fix

Merge accounts with same token/email/ID into single entry.

reset_active_index

fix

Reset active account index to valid range (0 to count-1).

clear_cooldown

fix

Remove expired cooldown timers (past reset time).

remove_invalid_fields

fix

Delete corrupted or schema-invalid metadata fields.

add_timestamps

fix

Set missing addedAt/lastUsed timestamps to current time.

migrate_storage

fix

Upgrade account storage from V1/V2 to V3 format.

update_quota_cache

fix

Refresh quota cache with live probe data (only with --live).

Examples

Preview fixes

codex auth fix --dry-run

Apply fixes

codex auth fix

Fix with live quota update

codex auth fix --live --model gpt-5-codex

Machine-readable output

codex auth fix --json

Count fixes needed

codex auth fix --dry-run --json | jq '.totalFixes'

Apply fixes and verify

codex auth fix
codex auth check --live
codex auth forecast --live

When to Run

After Errors

If you see storage or account errors:

codex auth fix
codex auth check

After Manual Edits

If you manually edited storage files:

codex auth fix --dry-run  # Preview
codex auth fix            # Apply

Periodic Maintenance

Weekly cleanup:

# Cron: Every Sunday at 2 AM
0 2 * * 0 codex auth fix --live

After Upgrades

After updating codex-multi-auth:

codex auth fix  # Migrate storage if needed
codex auth check --live

Exit Codes

exit code

Fixes completed successfully (or no fixes needed).

exit code

Fix operation failed (storage write error, network failure).

Performance

Default Mode

Speed: ~100-500ms
Network: Only for token refresh (if needed)
Writes: Single storage file update

Live Mode

Speed: ~2-3 seconds per account
Network: 1 API request per account + token refresh
Writes: Storage + quota cache updates

For 10 accounts with --live: ~30-40 seconds total.

Safety Guarantees

Backup Creation

Before any writes, a backup is created:

~/.codex/multi-auth/openai-codex-accounts.json.backup

If fix fails, restore with:

cp ~/.codex/multi-auth/openai-codex-accounts.json.backup \
   ~/.codex/multi-auth/openai-codex-accounts.json

Atomic Writes

Storage updates use atomic write-then-rename to prevent corruption.

Validation

All fixes are validated before write:

Schema compliance checked
Index bounds validated
Token format verified
Duplicate detection run

Troubleshooting

Fix Reports No Issues But Problems Persist

Run doctor for deeper diagnostics:

codex auth doctor --fix

Storage Backup Not Created

Check permissions:

ls -la ~/.codex/multi-auth/
chmod 755 ~/.codex/multi-auth/

Fix Fails with Write Error

Ensure directory is writable:

chmod 600 ~/.codex/multi-auth/openai-codex-accounts.json

On Windows, check file locks:

# Close any editors or tools accessing the file

Duplicate Merge Incorrect

Manually remove duplicates via dashboard:

codex auth login
# Select duplicate → press D (delete)

codex auth doctor - Full diagnostics with deeper repairs
codex auth check - Validate fixes worked
codex auth report - View current state
codex auth verify-flagged - Fix flagged accounts

Advanced Usage

Automated repair workflow

#!/bin/bash
set -e

# Preview fixes
codex auth fix --dry-run --json > fixes-preview.json

# If fixes needed, apply
if [ $(jq '.totalFixes' fixes-preview.json) -gt 0 ]; then
  codex auth fix --live --json > fixes-applied.json
  codex auth check --live
  codex auth forecast --live
fi

Pre-deployment checks

# CI/CD pipeline
codex auth fix --dry-run --json | jq '.totalFixes == 0'
# Exit code 0 if no fixes needed, 1 otherwise

Conditional live probe

# Only use live probe if many fixes needed
FIXES=$(codex auth fix --dry-run --json | jq '.totalFixes')

if [ $FIXES -gt 3 ]; then
  codex auth fix --live
else
  codex auth fix
fi

Commands

Configuration

Dashboard

​Usage

​What Gets Fixed

​Automatic Repairs

​Safe Operations Only

​Example Output

​Default Mode

​Dry Run Mode

​Live Mode

​JSON Output

​Fix Types

​Examples

​Preview fixes

​Apply fixes

​Fix with live quota update

​Machine-readable output

​Count fixes needed

​Apply fixes and verify

​When to Run

​After Errors

​After Manual Edits

​Periodic Maintenance

​After Upgrades

​Exit Codes

​Performance

​Default Mode

​Live Mode

​Safety Guarantees

​Backup Creation

​Atomic Writes

​Validation

​Troubleshooting

​Fix Reports No Issues But Problems Persist

​Storage Backup Not Created

​Fix Fails with Write Error

​Duplicate Merge Incorrect

​Related Commands

​Advanced Usage

​Automated repair workflow

​Pre-deployment checks

​Conditional live probe

Build docs developers (and LLMs) love

Usage

What Gets Fixed

Automatic Repairs

Safe Operations Only

Example Output

Default Mode

Dry Run Mode

Live Mode

JSON Output

Fix Types

Examples

Preview fixes

Apply fixes

Fix with live quota update

Machine-readable output

Count fixes needed

Apply fixes and verify

When to Run

After Errors

After Manual Edits

Periodic Maintenance

After Upgrades

Exit Codes

Performance

Default Mode

Live Mode

Safety Guarantees

Backup Creation

Atomic Writes

Validation

Troubleshooting

Fix Reports No Issues But Problems Persist

Storage Backup Not Created

Fix Fails with Write Error

Duplicate Merge Incorrect

Related Commands

Advanced Usage

Automated repair workflow

Pre-deployment checks

Conditional live probe