Getting Started

Getting started

This page takes you from nothing to a working multi-account setup: install codex-switch, add accounts, and pick the best one before a Codex session.

Requirements

• OpenAI Codex CLI installed, plus at least one ChatGPT account that can log in to Codex.
• Codex must use its file credential store, because codex-switch works by atomically replacing $CODEX_HOME/auth.json. If needed, add this to $CODEX_HOME/config.toml (normally ~/.codex/config.toml):

cli_auth_credentials_store = "file"

Explicit keyring, auto, and ephemeral stores are rejected — permanently by design, because OS keyrings cannot provide the locking and atomic-replace guarantees switching depends on (see why only the file store is supported). A managed Codex configuration with forced_login_method = "api" is also incompatible, because codex-switch manages ChatGPT login profiles. In both cases codex-switch stops with an actionable error instead of modifying authentication state; after switching to the file store, log in again.

Install

macOS / Linux:

curl -fsSL https://github.com/xjoker/codex-switch/releases/latest/download/install.sh | bash

This installs to the user-owned $HOME/.local/bin and configures PATH for zsh, bash, and fish; other shells receive a manual PATH instruction. An older direct install under /usr/local/bin is migrated once: the new user binary is installed first, then the installer removes the old copy with one elevated operation when required. Administrators can explicitly keep a system-wide install with --system; system installs may require sudo for later updates.

The installer verifies the download's SHA-256 checksum and, when a GitHub CLI with attestation support is present, its Sigstore build provenance — the same attestation self-update enforces, proving the archive was built by this repository's release workflow on a GitHub-hosted runner rather than merely matching a checksum published beside it. Provenance uses offline bundle verification, so it needs no gh auth login. If the GitHub CLI is unavailable the checksum is still enforced and provenance is skipped with a warning; set CS_REQUIRE_PROVENANCE=1 to make missing verification a hard failure.

If the installer says Installing to /usr/local/bin (requires sudo) without an explicit --system, stop it: that is the retired script from the repository's old master branch. Use the Release URL above.

Windows PowerShell:

irm https://github.com/xjoker/codex-switch/releases/latest/download/install.ps1 | iex

Windows installs under %LOCALAPPDATA%\Programs\codex-switch and updates the user PATH.

Homebrew (macOS / Linux):

brew install xjoker/tap/codex-switch

Homebrew distributes stable releases only and keeps ownership of its binary; update it with brew upgrade xjoker/tap/codex-switch, not with self-update.

Note: this project is not distributed on crates.io. Do not cargo install codex-switch — that package name belongs to an unrelated project of the same name.

Verify the installation:

codex-switch --version

Add your first account

codex-switch login work

login opens a browser PKCE flow; the alias (work) is optional and can be renamed later. On a headless machine, use the device-code flow instead:

codex-switch login --device server

If you already have auth.json backups, import a file or scan a whole directory. Imports are parsed, identity-checked, validated against the usage service, and saved under collision-free aliases. An import never overwrites an existing profile: a Team workspace ID proves access to that workspace, not ownership of another user's saved credentials.

codex-switch import ~/auth-backups

codex-switch also notices logins performed outside of it: when the live auth.json contains an account it does not track (for example after a plain codex login), an interactive run offers to save it as a profile.

Inspect quota and pick an account

codex-switch list        # accounts, quota, availability
codex-switch tui         # interactive dashboard
codex-switch use         # switch to the best eligible account
codex-switch launch      # select, start Codex, restore auth afterwards

use without an alias ranks all accounts with the adaptive scoring algorithm; use <alias> switches explicitly. Codex reads authentication at startup, so restart Codex after a manual switch — or use launch, which handles staging and restoration for you.

Where your data lives

Saved profiles, cache, configuration, and daemon state default to ~/.codex-switch (%USERPROFILE%\.codex-switch on Windows). The live Codex file stays at $CODEX_HOME/auth.json. See Configuration for every path and setting.

Never share profile files, auth.json, tokens, proxy credentials, or unredacted --debug output.

Next steps

• Learn account, quota, launch, and daemon workflows in the Feature guide.
• Look up exact commands and TUI shortcuts in the Command reference.
• Keep the binary current with Updating.