How to Switch Between Multiple Codex CLI Accounts Without Copying auth.json

A single Codex CLI home directory is convenient until one machine needs a personal account, a work account, and one or more client accounts. Manually replacing~/.codex/auth.json can leave the wrong account active, discard related state, or make token refresh behavior difficult to reason about. The account boundary should be explicit and repeatable instead.

Save each account as a named Codex profile

Use a profile name that describes the account's purpose. For an API-key account, pass the key through the normal aisw input. For ChatGPT-managed Codex auth, let the login happen inside the profile's isolated home rather than importing a file and assuming it will remain refreshable forever.

aisw init
aisw add codex personal --api-key "$PERSONAL_OPENAI_API_KEY"
aisw add codex work
aisw add codex client-acme
aisw list codex

The exact login prompt depends on the Codex CLI auth mode. The important part is the storage boundary: each named profile is managed locally, and its Codex state can be applied to the live process without editing hidden files yourself.

Switch accounts without copying auth.json

Activate the profile you want, check the result, and start a fresh Codex process. In the default isolated mode, aisw sets CODEX_HOME to the selected profile directory so Codex reads that profile's authentication, configuration, and related state together.

aisw use codex work --state-mode isolated
aisw status
aisw verify
codex

aisw use codex personal --state-mode isolated
codex

This is the account-switching loop people usually mean when they search for a Codex CLI account switcher: choose a named account, verify the live match, then launch Codex under that account. No shell script needs to move auth.json between directories.

Why isolated CODEX_HOME matters for ChatGPT-managed auth

Codex refreshes ChatGPT-managed credentials in place. Its upstream authentication documentationdescribes that persistence and refresh behavior. That makes an independently authenticated, profile-owned CODEX_HOME the durable path for multiple accounts. Each profile can refresh its own session without relying on a copied snapshot in a shared home directory.

A live import is useful when bootstrapping a profile that matches the account already open on the machine:

aisw add codex work --from-live
aisw use codex work --state-mode isolated

Treat that import as a starting point. For durable refresh behavior, authenticate the ChatGPT-managed account directly inside its isolated profile. Shared-mode switching for that auth is intentionally blocked because a shared refresh can invalidate the account snapshot you meant to keep.

API-key profiles have a different trade-off

API-key profiles do not need ChatGPT device authentication. You can save distinct keys as named profiles and choose shared mode when you intentionally want Codex to use its standard home. Isolated mode remains the clearer default when you also want configuration and local state separated.

aisw add codex client-a --api-key "$CLIENT_A_OPENAI_API_KEY"
aisw add codex client-b --api-key "$CLIENT_B_OPENAI_API_KEY"
aisw use codex client-a --state-mode isolated
aisw status --json

Keep API keys out of shell history and logs. Prefer environment variables or stdin when a script needs to provide a secret, and use JSON output for the non-secret result rather than printing credential material.

Use a context when a client setup includes other agents

A Codex profile is enough when only Codex changes. If a client repository also uses Claude Code, Gemini CLI, or Antigravity CLI, put the corresponding profiles behind one context so the entire account setup changes together.

aisw context create client-acme \
  --claude acme-claude \
  --codex acme-codex \
  --gemini acme-gemini
aisw context use client-acme
aisw status

Contexts are mappings, not another credential store. They are useful when your Claude, Codex, and Gemini profile names differ but the repository boundary is the same.

VS Code and Windows considerations

The profile model works from a terminal on macOS, Linux, and Windows. If Codex is running in VS Code or another editor, switch before starting the process that will use the account. A process that is already running may retain its previous environment and session; changing the selected profile does not rewrite an active conversation.

AI Switcher Desktop presents the same profiles and contexts through a visual interface. Use it when you want to inspect the active Codex account and repository binding before switching, then use the CLI when the same transition belongs in a repeatable script.

Protect repositories from account mistakes

If the wrong Codex account would expose a client repository to the wrong workspace, bind the repository to its expected context and enable a strict guardrail.

cd ~/src/client-acme-app
aisw workspace bind . --context client-acme
aisw workspace guard --mode strict

The shell hook checks the workspace before launching supported agent commands. Start in warn mode if you are auditing existing bindings, then move to strict mode once the expected context is correct.

What this approach does not promise

aisw manages deliberate account switching and one active live state per tool. It does not hot-swap credentials inside an already-running Codex process, bypass account limits, or make provider sessions interchangeable. For concurrent isolated Codex sessions, use Codex's own supported process and home-directory model, and keep each process's boundary explicit.

For the short command sequence, read How to Switch Codex CLI Accounts. For several named profiles, see Manage Multiple Codex CLI Accounts, then read the guide to using a Codex account per repository.