# codex-auth: switch between Codex accounts from the terminal > A Zig-written CLI distributed through npm that stores multiple Codex logins and swaps the active one. It is useful when you juggle a personal and a work ChatGPT account, and it is honest about its own rough edges. **Loongphy/codex-auth** — A CLI tool to switch and manage Codex accounts - Repository: https://github.com/Loongphy/codex-auth - Stars: 2,744 · Forks: 160 - Language: Zig - License: MIT - Published: 2026-09-28 · Updated: 2026-09-28 · Language: en - Canonical page: https://hysenlabs.com/projects/loongphy-codex-auth ## The problem: one Codex login slot, several accounts Codex clients keep a single authenticated identity in `~/.codex`. If you have a personal ChatGPT plan and a work seat, moving between them means signing out, signing in, and redoing whatever the client lost in the process. `codex-auth` treats those logins as a collection instead of a single slot: it stores each account's auth file, keeps a registry of them, and rewrites the active one on demand. The audience is narrow and specific. It is for people who already run the Codex CLI, the VS Code extension, or the Codex App and who own more than one account for those clients. A single-account user gains nothing from installing it, because the whole tool is a management layer over a set of accounts that would otherwise be a set of one. ## How the registry, imports and exports fit together The tool keeps stored auth files plus a `registry.json` that indexes them. `codex-auth import` adds a single auth file or walks a folder for a batch, with an optional `--alias`; `codex-auth import --purge` rebuilds the registry from the auth files already on disk, which is the recovery path when the index and the files disagree. `codex-auth export` goes the other direction and writes stored auth files back out, and `--cpa` on both import and export converts to and from CLIProxyAPI token JSON. Accounts can be labelled with `codex-auth alias set `, and selectors accept either a row number such as `02` or a name such as `work`, which is why aliases are worth setting before a collection grows. Usage state is refreshed from one of two sources. The default makes HTTPS requests to OpenAI's endpoints with the account's access token, which the README says also refreshes team names, and it requires `curl` at runtime. The `--skip-api` flag switches a single command to scanning local `~/.codex/sessions/*/rollout-*.jsonl` files instead. The project is written in Zig, and the npm package ships prebuilt binaries per platform through optional dependencies rather than compiling on install. ## Install codex-auth and make your first switch The README installs the tool globally through npm, and the package name carries the scope. ```bash npm install -g @loongphy/codex-auth ``` There is also a no-install path if you only want to look at what is stored: ```bash npx @loongphy/codex-auth list ``` The README recommends installing the Codex CLI even if you mainly use the VS Code extension or the App, because it makes adding accounts easier. Once it is present, `codex-auth login` runs `codex login` and then adds whatever account you just authenticated. The `--device-auth` flag routes that sign-in through the device flow. ```bash npm install -g @openai/codex codex-auth login ``` With two accounts stored, switching is either interactive or direct. A direct selector can be a row number or an alias. ```bash codex-auth switch codex-auth switch 02 ``` After the switch, restart the client. The README is explicit that Codex CLI and Codex App users must restart for the new account to take effect. To confirm the account is live, the README suggests a plain Codex invocation: ```bash codex exec "say hello" ``` If you are building something on top of the tool rather than using it by hand, the `--json` variants of supported commands return machine-readable results under a documented compatibility contract in `docs/json-api.md`. ## Usage refresh: the API default and the local fallback The two refresh modes are not equivalent, and the README does not pretend they are. API-backed refresh is the default, and it sends the account's ChatGPT access token to OpenAI's servers to read usage limits and team names. The exact endpoints are listed in the disclaimer. Local-only mode, selected per command with `--skip-api`, scans rollout files under `~/.codex/sessions` and skips the team name calls. The README states that recent Codex builds often write `token_count` events with `rate_limits: null`, so local files may still hold older usable data but can lag by several hours. That is a real trade-off rather than a bug in this tool: the upstream issue it points to is openai/codex#14880. Practically, `--skip-api` is the option for a machine where you would rather not hand the token to a network call, and the cost is a usage snapshot that may be hours stale. The API path costs a runtime dependency on `curl` and a network round trip on every command that refreshes. ## Where codex-auth stops being the right tool The sharpest limitation is the restart. Switching an account does not migrate an open session, so any workflow that depends on changing identity mid-conversation is out of scope for this tool. The README points at a separate project, the forked `codext`, for automatic switching without restarts, which tells you the author considers that a different product rather than a missing feature here. The `codex-auth app` command is the attempt to close that gap for the Codex App, and the README labels it experimental, says it may never become a stable feature, and warns that it may not take effect and may break your app. It works by injecting a managed `codext` CLI through the `CODEX_CLI_PATH` environment variable, and it is constrained by changes in both the official Codex App and the upstream Codex CLI. Treat it as a thing to try on a machine you can afford to repair, not as the reason to adopt the project. There is also no rollback command. `clean` deletes managed backup and stale account files, and `import --purge` rebuilds the registry, but the README does not document undoing a switch or restoring a previous active account, so keep your own copy of anything you cannot re-authenticate. ## codex-auth compared with the manual approach and with codext The obvious alternative is doing nothing: sign out in the client, sign in with the other account, and keep the auth files yourself. That approach has no dependency on `curl`, sends no token anywhere, and cannot break your App. It also has no registry, no aliases, no batch import, no usage view, and no JSON output for scripting, and each switch costs a full interactive login. `codex-auth` trades the manual login for a stored file swap plus a client restart. The second alternative is `codext`, which the README describes as an enhanced fork of the Codex CLI that handles authentication on the fly so no restart is needed. The difference in approach is architectural: `codex-auth` manages accounts around an unmodified client, while `codext` replaces the client to move the switch inside it. That makes `codext` the better fit for uninterrupted switching and `codex-auth` the better fit if you want to keep running the official Codex CLI, extension, or App as they are. The README suggests installing `codext` with `npm i -g @loongphy/codext` and running `codext`, and notes that Codex App users can reach for `codex-auth app` instead, with the stability caveats above. ## Licence, maintenance and what an upgrade costs you The project is MIT licensed, and `package.json` declares the same, so the usual MIT permissions and the usual absence of warranty apply; the README carries its own as-is disclaimer and notes that default API-backed refresh transmits your ChatGPT access token to OpenAI. That is a data-handling decision to make deliberately, not a licensing question, and it is the part worth reading in full before you point the tool at a work account. On maintenance, the last push to the default branch was on 2026-09-15, and v0.3.0 was released the same day, following a run of v0.3.0-alpha builds and v0.2.10. The repository is not archived. Upgrades are npm upgrades of a scoped package with per-platform optional dependencies pinned to the same version, so a global install moves the binary and the wrapper together. The costs to plan for are the ones the README names: the `curl` runtime dependency for the default refresh path, the client restart after every switch, and the fact that the experimental `app` command can break when either the Codex App or the upstream Codex CLI changes, which is outside this project's control. ## Conclusion Adopt codex-auth if you regularly move between two or more Codex accounts on one machine and want that swap to be a single command rather than a manual file copy. Do not adopt it if you need switching to happen while a session is already open: the README states that Codex CLI and Codex App users must restart the client, and the no-restart path is the separate `codext` fork. Before relying on it, run `codex-auth list` once with the API enabled and once with `--skip-api` to see how far apart the two usage snapshots are on your machine, and check whether `curl` is present, since the default refresh path requires it. ## FAQ ### What is codex-auth? It is a command-line tool for switching Codex accounts, written in Zig and distributed through npm as @loongphy/codex-auth. It stores multiple account auth files, keeps a registry of them, and rewrites the active account on request. ### Where does codex-auth keep the auth JSON? The README does not state a directory for the stored auth files themselves. It documents `registry.json` as the index that `codex-auth import --purge` rebuilds, and it names `~/.codex/sessions/*/rollout-*.jsonl` as the local files scanned in `--skip-api` mode. ### How do I install codex-auth? Install it globally with npm using the scoped package name, or run a single command through npx without a global install. The npm package ships prebuilt binaries for Linux, macOS and Windows on x64 and arm64 as optional dependencies. ### Why is my usage limit not refreshing in codex-auth? The README explains that recent Codex builds often write `token_count` events with `rate_limits: null`, so local-only refresh via `--skip-api` can show a snapshot from hours ago. API-backed refresh is the default and is the mode to use when you need current usage data. ### Does codex-auth need curl? The README states that `curl` must be available at runtime for the default API-backed usage refresh. The `--skip-api` flag avoids that path for a single command by scanning local rollout files instead. ## Sources - [Issues](https://github.com/Loongphy/codex-auth/issues) - [License: MIT](https://github.com/Loongphy/codex-auth/blob/main/LICENSE) - [Loongphy/codex-auth on GitHub](https://github.com/Loongphy/codex-auth) - [README](https://github.com/Loongphy/codex-auth/blob/main/README.md) - [Releases](https://github.com/Loongphy/codex-auth/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/loongphy-codex-auth