Codex Profiles

Seamlessly switch between multiple Codex accounts

Overview • Install • Usage • More Docs • FAQ

---

Overview

Codex Profiles lets you save and switch between multiple Codex accounts without repeated codex login. It manages file-backed account credentials; Codex's native --profile option independently selects configuration settings.

Install

Method	Command
npm	npm install -g codex-profiles
Bun	bun install -g codex-profiles

Manual install

curl -fsSL https://raw.githubusercontent.com/midhunmonachan/codex-profiles/main/install.sh | bash

Advanced install option (build from source)

cargo install --locked codex-profiles

Requires Rust 1.94+

Quick Start

codex-profiles save --label work
codex-profiles list
codex-profiles load --label work --force
codex-profiles status --all --compact

Usage

Note

Codex Profiles data is stored under $CODEX_HOME/profiles/, or ~/.codex/profiles/ when CODEX_HOME is unset.

Command Reference

Command	Description
codex-profiles save [--label <name>]	Save current auth.json Optional label
codex-profiles load [--label <name> | --id <profile-id>] [--force] [--with-status]	Load a saved profile Add --with-status to show usage and reset times
codex-profiles list [--show-id] [--json]	List profiles Supports id and JSON views
codex-profiles export --output <file> [--label <name> | --id <profile-id> (repeatable)]	Export to a JSON bundle Default: all profiles, or a selected subset
codex-profiles import --input <file>	Import from a JSON bundle
codex-profiles doctor [--fix] [--json]	Check account storage and local Codex configuration, and optionally repair profile storage
codex-profiles label set (--label <name> | --id <profile-id>) --to <label>	Set or replace a label Target one profile
codex-profiles label clear (--label <name> | --id <profile-id>)	Clear a label Target one profile
codex-profiles label rename --label <label> --to <label>	Rename an existing label
codex-profiles status [--label <name> | --id <profile-id>] [--all] [--json | --compact]	Show usage for active, selected, or all accounts --compact requires --all and groups short usage lines by account and bucket
codex-profiles delete [--label <name> | --id <profile-id> (repeatable)] [--yes]	Delete by label or id Supports bulk delete and non-interactive mode

Notes

• load and delete open a profile picker unless you pass --label or --id. Selecting a profile does not skip other prompts: load may ask about unsaved active credentials, and delete requires confirmation unless you pass --yes.
• With load --with-status, the profile still switches even if the status check fails
• status --all --compact shows remaining usage and reset times without progress bars. Use --json for scripts; it cannot be combined with --compact.
• Usage windows use the durations reported by Codex, including weekly-only and custom limits. Missing data is shown as unavailable.
• Finish active Codex work before switching and restart the affected client afterward. See client compatibility.
• Export bundles contain secrets
• Export refuses existing output paths, including dangling symlinks and files created during export. The output filesystem must support hard links; an unsupported filesystem returns an error without replacing the destination.
• Import also refuses a profile path created during the operation and requires hard-link support and readable file identities. On failure, rollback checks file identity and contents and reports any files it cannot safely verify or remove. Inspect the store before retrying an incomplete rollback. Keep other writers out of the store during import; rollback is not a filesystem transaction.

More Docs

• Client compatibility and credential storage
• Release verification guide
• Contribution guide
• Project status and release research
• Optional config snapshots: design proposal (not implemented)

FAQ

How do I uninstall?

• npm: npm uninstall -g codex-profiles
• Bun: bun uninstall -g codex-profiles
• Cargo: cargo uninstall codex-profiles
• Manual: rm ~/.local/bin/codex-profiles

Is my auth file uploaded anywhere?

Saved profiles stay on your machine. For OAuth profiles, status may send the access token to the configured allowed usage endpoint and may refresh it through OpenAI after an unauthorized response. API-key profiles show usage as unavailable. Update checks contact package/release services. Export bundles contain credentials and should be treated like passwords.

What is a “profile” in this tool?

An account profile is a saved copy of $CODEX_HOME/auth.json (by default, ~/.codex/auth.json). Native codex --profile NAME selects a configuration layer and does not switch these saved accounts.

What happens if I run load without saving?

When the active credentials are unsaved, an interactive terminal prompts you to save them, continue without saving, or cancel. In scripts, save them first or explicitly use --force to continue without saving. A --label or --id selector alone does not skip this check.

Can I keep personal and work accounts separate?

Yes. Save each account with a label (for example, personal and work) and switch with the label

How can I verify my installation?

codex-profiles --version
codex-profiles list

Where are release verification steps documented?

In docs/verification.md