codex-ctx

Switch Codex CLI auth contexts without wrapping the codex command.

codex-ctx switches only ~/.codex/auth.json. Your Codex sessions, config, logs, caches, and history stay shared in ~/.codex.

Install

npm install -g codex-ctx

Usage

Initialize codex-ctx from your current Codex login:

codex-ctx init

Add another account:

codex-ctx create work
codex login
codex-ctx add work

create starts a blank context for the next login. add saves the currently active Codex login into a named context.

Switch accounts before starting Codex:

codex-ctx use default
codex

codex-ctx use work
codex

List and inspect contexts:

codex-ctx list
codex-ctx current
codex-ctx doctor

Remove a context:

codex-ctx remove work

Rename a context:

codex-ctx rename work company

Commands

codex-ctx init             # save current ~/.codex/auth.json as default
codex-ctx add <name>       # save current ~/.codex/auth.json as a context
codex-ctx create <name>    # create an empty context and clear active auth
codex-ctx use <name>       # restore a saved context to ~/.codex/auth.json
codex-ctx rename <old> <new>
codex-ctx list             # list saved contexts
codex-ctx current          # show current context
codex-ctx remove <name>    # remove a saved context
codex-ctx doctor           # show storage and auth status

Aliases:

init --force overwrites the saved default context with the current active auth.

save   -> add
new    -> create
switch -> use
mv     -> rename
ls     -> list
status -> current
rm     -> remove
delete -> remove

Storage

Shared Codex home:

~/.codex/
  auth.json
  config.toml
  sessions/
  log/
  cache/

Auth contexts:

~/.codex-auth-contexts/
  personal/auth.json
  work/auth.json

State:

~/.codex-ctx/
  current

Notes

codex-ctx does not install a codex wrapper and does not modify your shell PATH. Run codex-ctx use <name> before codex.

If you previously used the experimental codex ctx wrapper, remove it manually if needed:

rm ~/.local/bin/codex
hash -r 2>/dev/null || rehash

Only remove that file if it is the codex-ctx wrapper.

Security

codex-ctx copies Codex auth files on your local machine. It does not upload credentials or talk to a network service. Treat ~/.codex-auth-contexts with the same care as ~/.codex/auth.json.