codex-auth-snap

English | 中文

Tiny, auditable, offline Codex ChatGPT auth.json snapshot switcher for macOS, built for high-volume coding workflows with multiple authorized ChatGPT accounts.

codex-auth-snap is a minimal zsh CLI for developers who code a lot with Codex and want a clean way to switch between their own authorized ChatGPT accounts on one machine. It saves and restores local auth.json snapshots. It has no third-party runtime dependencies, does not install a dependency tree, does not call the network, and never prints credential contents.

This project is not affiliated with OpenAI.

Why This Project Exists

Codex ChatGPT auth can be stored in:

$CODEX_HOME/auth.json

If you have more than one authorized Codex account on the same Mac, switching accounts is really a local file operation: save the current auth.json, restore another one, then restart Codex so it rereads the file.

This tool makes that workflow explicit, repeatable, and easy to inspect.

Who It Is For

This project is for developers, builders, and AI power users who:

• Use Codex heavily for programming, refactoring, debugging, and agentic coding.
• Keep multiple authorized ChatGPT or ChatGPT Plus accounts for legitimate personal, work, region, team, or billing separation.
• Want fast account switching without browser gymnastics, dependency-heavy tools, background agents, or network services.
• Prefer a tiny local CLI whose behavior can be inspected in one file.

It is not for credential sharing, account pooling, or policy evasion.

Highlights

• Tiny CLI logic: one zsh script, direct file operations, no daemon, no background service.
• Zero third-party runtime dependencies: no npm package tree, no pip environment, no bundled dependency chain.
• Smaller supply-chain attack surface: the first public release depends only on zsh and standard macOS tools such as plutil and BSD stat.
• Offline by design: no network requests, no OpenAI API calls, no telemetry.
• Concrete safety properties: strict file permissions, symlink refusal, bounded JSON output, token redaction, cloud-sync warnings.
• Easy to audit: the core behavior is in a single shell script, and the test suite uses temporary directories only.

Search Keywords

Useful search terms for this project:

Codex account switcher
Codex auth switcher
Codex auth.json switcher
Codex login switcher
OpenAI Codex account switcher
ChatGPT account switcher
ChatGPT Plus account switcher
multiple ChatGPT accounts
multiple Codex accounts
switch ChatGPT accounts on macOS
offline CLI
no dependency CLI
zero dependency shell script
supply chain safe CLI
local-first auth switcher
macOS zsh CLI

Suggested GitHub topics:

codex
chatgpt
openai
codex-cli
codex-auth
auth-switcher
account-switcher
chatgpt-plus
macos
zsh
cli
offline
no-dependencies
supply-chain-security
local-first

Security Claim

No CLI can honestly promise absolute safety against malware, a compromised local user account, or manual credential sharing.

What codex-auth-snap does promise is narrower and verifiable:

• It never sends network requests.
• It never calls codex logout.
• It never refreshes tokens.
• It never decodes JWTs.
• It never prints access_token, refresh_token, id_token, or full auth.json content.
• It refuses symlinked auth paths and state files.
• It writes state directories with mode 700.
• It writes auth snapshots and state files with mode 600.

Treat every auth.json and *.auth.json as a password.

What It Does

• Saves the active Codex ChatGPT auth.json as a named local snapshot.
• Restores a saved snapshot into $CODEX_HOME/auth.json.
• Supports a safe login flow for adding another account.
• Keeps snapshot and state file permissions strict.
• Provides a doctor command for local diagnostics.
• Provides --json output for automation and agent-friendly tooling.

What It Does Not Do

• It does not share, pool, sell, or broker accounts.
• It does not bypass usage limits, bans, rate limits, or policy enforcement.
• It does not automate account rotation.
• It does not call OpenAI APIs or any other network service.
• It does not parse, export, or print token values.

Only use this tool with accounts that you own or are explicitly authorized to use.

Platform Support

First public release scope:

• macOS
• zsh
• Codex configured for file-backed ChatGPT auth

Linux support is not claimed yet.

Install

From the repository root, install the script into your user bin directory:

./codex-auth-snap install

The default install path is:

$HOME/.local/bin/codex-auth-snap

If ~/.local/bin is on your PATH, you can run:

codex-auth-snap version

You can also install to a custom location:

./codex-auth-snap install --bin-dir "$HOME/bin"
./codex-auth-snap install --prefix "$HOME/.local"

install copies the current script. Re-run install after upgrading the repository checkout.

Quick Start

Initialize Codex file-backed auth:

codex-auth-snap init --fix
codex-auth-snap --json doctor

Save the account that is currently logged in:

codex login
codex-auth-snap save personal

Add another account:

codex-auth-snap begin-login work
codex login
codex-auth-snap finish-login

Switch accounts:

codex-auth-snap use personal
# Restart Codex CLI or Codex App so it reads the restored auth.json.

codex-auth-snap use work
# Restart Codex CLI or Codex App again.

List saved snapshots:

codex-auth-snap list
codex-auth-snap current

Read the full guide in docs/quickstart.md.

Paths

Default Codex auth path:

CODEX_HOME=${CODEX_HOME:-$HOME/.codex}
AUTH_FILE=$CODEX_HOME/auth.json

Default snapshot state path:

CODEX_AUTH_SNAP_HOME=${CODEX_AUTH_SNAP_HOME:-$HOME/.codex-auth-snap}

State layout:

$CODEX_AUTH_SNAP_HOME/
├── accounts/
├── meta/
├── before-login/
├── current
├── pending-login
└── lock/

Permission rules:

directories: 700
auth.json / *.auth.json / meta / current / pending-login: 600

CODEX_AUTH_SWITCH_HOME and CODEX_SWAP_HOME are still accepted as legacy state directory variables for migration. If multiple variables are set, CODEX_AUTH_SNAP_HOME wins.

Commands

codex-auth-snap [--json] init [--fix] [--force]
codex-auth-snap [--json] save <name> [--force]
codex-auth-snap [--json] use <name> [--force]
codex-auth-snap [--json] begin-login <name> [--force]
codex-auth-snap [--json] finish-login [name] [--force]
codex-auth-snap [--json] abort-login [--force]
codex-auth-snap [--json] install [--prefix <dir>|--bin-dir <dir>] [--force]
codex-auth-snap [--json] list
codex-auth-snap [--json] current
codex-auth-snap [--json] remove <name> [--active-too]
codex-auth-snap [--json] doctor
codex-auth-snap [--json] paths
codex-auth-snap [--json] version

Account names may contain ASCII letters, digits, dots, underscores, and hyphens.

JSON Output

All commands support --json. In JSON mode, stdout contains one envelope:

{
  "content": [{"type": "text", "text": "short summary"}],
  "structuredContent": {"result": {}},
  "isError": false
}

Business failures return a non-zero exit code:

{
  "content": [{"type": "text", "text": "short error"}],
  "structuredContent": {
    "error": {
      "code": "stable_error_code",
      "message": "what failed",
      "retryable": false,
      "field_errors": [],
      "suggested_fix": "what to do next"
    }
  },
  "isError": true
}

JSON output is intentionally bounded. list only shows account aliases, saved timestamps, current markers, and short hashes.

Safety

• Do not commit auth snapshots.
• Do not share auth snapshots.
• Do not copy auth snapshots to another machine.
• Do not place snapshot state in iCloud, Dropbox, Google Drive, OneDrive, or another sync directory.
• Do not run multiple Codex sessions against the same account snapshot at the same time.
• Restart Codex CLI or Codex App after switching accounts.

See SECURITY.md and docs/security-model.md.

Troubleshooting

Run:

codex-auth-snap --json doctor

doctor checks local paths, file-backed auth configuration, state permissions, symlink risk, invalid JSON, pending login state, installed copy drift, cloud sync path risk, and running Codex processes.

See docs/troubleshooting.md.

Tests

The test suite uses temporary directories and does not touch your real ~/.codex:

zsh tests/test_codex_auth_snap.sh

License

MIT. See LICENSE.