Bash CLI for Codex profiles: usage and proxy

Bash CLI Tool for Switching Codex Profiles

When juggling multiple Codex accounts—work, personal, backup—the default ~/.codex/auth.json file turns into a major bottleneck. Manually copying auth files leads to confusion: you lose track of which profile is active, how much quota remains, and risk overwriting important data. A simple bash script called codex-auth fixes this by adding commands to save, switch profiles, and monitor usage via the API.

The script stores profiles separately, caches usage data, supports proxies, and detects duplicate accounts via fingerprints.

Location of auth.json and Cross-Platform Notes

Main authorization file:

• Linux/macOS: ~/.codex/auth.json
• Windows: %USERPROFILE%\.codex\auth.json

It contains access_token, id_token, and account_id. The structure might change, so parsing uses jq with fallbacks.

Issues with manual cp:

• No indicator of the active profile
• Risk of data loss
• No info on quotas or reset times

Script Commands

The script offers a clean CLI interface:

• codex-auth — list profiles with usage
• codex-auth usage — quotas for current auth.json
• codex-auth save <name> — save current profile
• codex-auth use <name> — switch profiles (or shorthand codex-auth <name>)
• codex-auth list-fast — local list without API calls
• codex-auth backup — backup current profile

Proxy support:

• codex-auth proxy set <url>
• codex-auth proxy show
• codex-auth proxy unset

Caching:

• codex-auth cache-time [seconds] (default 15s, 0 disables cache)

Example Usage

• Log in with work account: codex-auth save work
• Log in with personal: codex-auth save personal
• Switch: codex-auth work or codex-auth personal
• Output:

📊 5h: 100% ⏱5h   7️⃣ 15% ⏱4d 9h      work      <[email protected]>     
📊 5h: 100% ⏱5h   7️⃣ 84% ⏱3d 18h    *personal  <[email protected]>

Monitoring Usage via API

Query to https://chatgpt.com/backend-api/wham/usage with Authorization: Bearer $token and account_id in headers:

curl -s \
  -H "Authorization: Bearer $token" \
  -H "Accept: application/json" \
  -H "User-Agent: CodexCLI" \
  "https://chatgpt.com/backend-api/wham/usage" | jq

Parsing shows:

• Account email
• Plan type
• Remaining quota (5h, weekly)
• Reset time
• Code review limit

Caching for Speed

Cache stored in ~/.codex-auth-profiles/.usage-cache, keyed by token + account_id + proxy. Configurable TTL avoids unnecessary API calls. No cache (TTL=0) fetches fresh data every time.

Proxy Support

For corporate networks or firewalls:

codex-auth proxy set http://127.0.0.1:8888

curl uses --proxy for all requests. Stored in ~/.codex-auth-profiles/proxy.

Detecting Duplicates

Profile fingerprint:

• account_id
• sub from id_token
• Email
• SHA256 of entire file

Prevents duplicates under different names and checks matches with active auth.json.

Cross-Platform Adaptations

• base64: Linux base64 -d, macOS base64 -D
• stat: Linux stat -c %Y, macOS stat -f %m
• SHA256: Linux sha256sum, macOS shasum -a 256

Atomic writes via mktemp + mv.

Profiles in ~/.codex-auth-profiles: JSON files for profiles, current selection, settings, and cache.

Limitations

• Depends on auth.json structure
• Backend API may change
• Bash only, not for complex logic

Dependencies: bash, jq, curl, awk, sort, base64, stat.

Key Benefits

• Switch profiles without risking auth.json overwrites
• Usage monitoring with visual quotas and resets
• TTL caching for speed, proxy support for networks
• Fingerprints prevent duplicates
• Atomic writes, fully cross-platform

— Editorial Team