codex-account-switcher

Secure local CLI for switching between Codex accounts that are already authorized on your machine.

codex-switch uses official codex login and codex logout flows for account authorization and stores saved auth snapshots as encrypted opaque files.

Important

This tool is designed for Windows because it uses Windows DPAPI encryption for profile snapshots.

Warning

Do not upload your local .\.codex-switch\ folder. It contains encrypted local auth snapshots and backup metadata created on your machine.

Install From GitHub

git clone https://github.com/ljdstechva/codex-account-switcher.git
cd codex-account-switcher

Requirements

Requirement	Minimum	Why
OS	Windows 10/11	Uses Windows DPAPI encryption APIs
Python	3.10+	Runs the CLI (codex_switch.py)
Codex CLI	Installed and on PATH	Used for login, logout, login status, and rate-limit refresh

First Run

python --version
.\codex-switch.cmd --help
.\codex-switch.cmd doctor

If no profile is saved yet, snapshot your current active account first:

.\codex-switch.cmd add --from-current --label personal

This tool does not bypass OAuth, decrypt browser sessions, scrape cookies, print tokens, upload credentials, or access accounts you did not personally authorize.

Commands

Run from this folder:

.\codex-switch.cmd --help
.\codex-switch.cmd list
.\codex-switch.cmd current
.\codex-switch.cmd add
.\codex-switch.cmd switch
.\codex-switch.cmd remove <label-or-id>
.\codex-switch.cmd rename <label-or-id> --label <new-label>
.\codex-switch.cmd validate
.\codex-switch.cmd rollback
.\codex-switch.cmd doctor

Aliases are also provided:

.\codex-account-switcher.cmd
.\account-switcher.cmd

Running .\codex-switch.cmd with no arguments opens the interactive menu. Use Up/Down and Enter to select; Esc or q cancels a selector.

What It Does

• Shows saved local Codex account profiles.
• Detects the active Codex CLI login with codex login status.
• Matches the active auth cache to a saved encrypted profile when possible.
• Adds accounts through the official Codex OAuth/device login flow.
• Saves the current Codex auth cache as an encrypted profile.
• Switches accounts by restoring a selected encrypted Codex auth snapshot.
• Creates an encrypted backup before every switch.
• Restarts Codex Desktop automatically after a successful switch.
• Uses arrow-key selection in the interactive menu and account picker.
• Shows 5-hour and weekly rate-limit remaining percentages where Codex reports them.
• Refreshes rate-limit data only when you choose Refresh rate limits or run refresh-rates.
• Supports rollback to the last backup.
• Runs environment checks with doctor.

What It Does Not Do

• It does not make unauthorized accounts accessible.
• It does not bypass OAuth or account security.
• It does not print, parse, or expose token values.
• It does not modify non-Codex application data.
• It does not silently bypass Codex Desktop limitations; it restarts the desktop app after switching so the UI can reload account state.

Security Model

On this Windows machine, saved profiles are encrypted using Windows DPAPI for the current Windows user. The metadata file stores only labels, optional email text supplied by you, timestamps, the Codex auth path, and references to encrypted snapshot files.

The encrypted snapshot files contain opaque copies of Codex's own auth.json file. They are required for switching, but the CLI does not parse or print their contents. The data directory is created at:

.\.codex-switch

The tool tries to restrict permissions on its data directory and files. Backups are stored encrypted under:

.\.codex-switch\backups

Rate-limit refreshes use Codex's official local app-server method account/rateLimits/read. To check saved profiles without switching your real Codex home, the CLI creates a short-lived secured temporary Codex home under .\.codex-switch\tmp, writes the selected profile's opaque auth snapshot there, reads rate limits, re-encrypts any refreshed auth snapshot back into the saved profile, then deletes the temporary directory. Refreshing is explicit: use the interactive Refresh rate limits menu item or run .\codex-switch.cmd refresh-rates.

Confirmed Local Codex Paths

Local inspection found:

C:\Users\USER\.codex\auth.json
C:\Users\USER\.codex\config.toml
C:\Users\USER\AppData\Roaming\npm\codex.ps1
C:\Users\USER\AppData\Local\OpenAI\Codex\bin\codex.exe
C:\Users\USER\AppData\Local\Packages\OpenAI.Codex_2p2nqsd0c76g0

The current Codex CLI reported:

codex-cli 0.118.0
Logged in using ChatGPT

Add Accounts

To save the currently active Codex login as the first profile:

.\codex-switch.cmd add --from-current --label personal

To add another account through the official browser OAuth flow:

.\codex-switch.cmd add --label work

The add flow:

1. Creates an encrypted backup of the current Codex auth cache.
2. Runs codex logout.
3. Runs codex login or codex login --device-auth.
4. Waits for you to complete the official OAuth/device flow.
5. Saves the new auth cache as an encrypted profile.
6. Restores the previously active account unless you pass --keep-active.

For headless/device auth:

.\codex-switch.cmd add --label work --device-auth

To preview without logging out or opening OAuth:

.\codex-switch.cmd add --label work --dry-run

List Accounts

.\codex-switch.cmd list

list shows cached rate limits for saved accounts: 5h left, 5h reset, Weekly left, and Weekly reset.

Rate colors on dark terminals:

• Red: 0%
• Orange/yellow: 1% to 20%
• Green: above 20%

To update the cached rate limits:

.\codex-switch.cmd refresh-rates

Switch Accounts

Interactive arrow-key flow:

.\codex-switch.cmd

Choose Switch account, select an account with Up/Down, then press Enter. After selection, the account list clears and only progress plus the final notification is shown.

Use Refresh rate limits from the main menu whenever you want fresh values. Switching uses the cached values already available instead of forcing a fresh blocking refresh every time.

Dry run:

.\codex-switch.cmd switch work --dry-run

Switch immediately:

.\codex-switch.cmd switch work

Switch without restarting Codex Desktop:

.\codex-switch.cmd switch work --no-restart

The switch command no longer asks for yes/no confirmation. It creates a backup first, restores the selected encrypted snapshot to Codex's auth.json, validates with codex login status, displays the selected account's cached rate limits, then restarts Codex Desktop automatically. If validation fails, it restores the backup automatically.

Current Account

.\codex-switch.cmd current

The current account is detected by codex login status and by comparing the active opaque auth cache to encrypted saved profiles. In this environment, official status output does not expose the account email, so email is optional metadata that you can provide yourself.

Rollback

.\codex-switch.cmd rollback

Rollback restores the most recent encrypted backup. It creates another backup before rollback so the operation can be reversed manually if needed.

Doctor

.\codex-switch.cmd doctor

Doctor checks:

• OS and Python version
• Codex CLI presence and version
• Codex Desktop likely presence
• Codex auth/config paths
• Active login status
• Profile storage writability
• DPAPI encryption self-test
• Backup support
• Known limitations

Files Read And Written

Read-only discovery:

• ~\.codex\config.toml
• Codex install locations
• Codex Desktop package locations

Runtime Codex auth operations:

• Reads ~\.codex\auth.json as opaque bytes.
• Writes ~\.codex\auth.json only when you run switch, rollback, or the official add flow.
• Invokes codex login, codex logout, and codex login status.

Tool-owned files in this folder:

• .\.codex-switch\profiles.json
• .\.codex-switch\profiles\...\auth.dpapi
• .\.codex-switch\backups\...\auth.dpapi
• .\.codex-switch\backups\...\backup.json

Known Limitations

• If Codex is configured to store auth only in the OS keychain and no auth.json exists, this tool will not snapshot or switch that auth. Use the official Codex login/logout flow instead.
• Codex Desktop may cache state while running. switch now restarts Codex Desktop automatically; pass --no-restart only for tests or unusual workflows.
• The CLI can validate that Codex is logged in, but this local codex login status output does not reveal the email address.
• Encrypted profile snapshots are Windows-user and machine scoped through DPAPI.

Development And Tests

Run:

python -m py_compile .\codex_switch.py
python -m unittest discover -s tests
.\codex-switch.cmd --help
.\codex-switch.cmd list
.\codex-switch.cmd current
.\codex-switch.cmd doctor
.\codex-switch.cmd add --label test-oauth --dry-run
.\codex-switch.cmd switch <label> --dry-run --no-restart