Codex Profiles

Manage multiple Codex CLI profiles and switch between them instantly.

Overview • Install • Uninstall • Usage • FAQ

---

Overview

Codex Profiles helps you manage multiple Codex CLI logins on a single machine. It saves the current login and lets you switch in seconds, making it ideal for personal and team accounts across multiple organizations.

Install

Note

npm, bun, and the manual installer use prebuilt native binaries. cargo install --locked codex-profiles builds locally from source if you prefer not to run prebuilt binaries.

Tip

Looking for a Teams promo? See details

NPM

npm install -g codex-profiles

Bun

bun install -g codex-profiles

Cargo

cargo install --locked codex-profiles

Manual Install

Automatically detects your OS/architecture, downloads the correct binary, and verifies checksums when verification tooling is available:

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

Uninstall

NPM

npm uninstall -g codex-profiles

Bun

bun uninstall -g codex-profiles

Cargo

cargo uninstall codex-profiles

Manual Uninstall

rm ~/.local/bin/codex-profiles

Usage

Tip

load and delete are interactive unless you pass --label or --id. If the current profile is not saved, load also prompts before switching unless you pass --force.

Command	Description
codex-profiles save [options]	Save the current auth.json as a profile. Use --label <name> to label it.
codex-profiles load [options]	Load a profile without re-login. Use --label <name>, --id <profile-id>, and --force as needed.
codex-profiles list [options]	List saved profiles. Use --show-id or --json for alternate output.
codex-profiles export [options]	Export saved profiles to a single JSON bundle.
codex-profiles import [options]	Import saved profiles from a JSON bundle.
codex-profiles doctor [--fix] [--json]	Run local diagnostics and optionally apply safe metadata repairs.
codex-profiles label set [options]	Add or replace a label on a saved profile.
codex-profiles label clear [options]	Remove a label from a saved profile.
codex-profiles label rename [options]	Rename an existing label without using set/clear manually.
codex-profiles default [set|clear|show]	Manage the default saved profile used by non-interactive load.
codex-profiles status [options]	Show usage for the current profile, a selected saved profile (--label/--id), or all saved profiles with --all. Use --json for structured output.
codex-profiles delete [options]	Delete profiles. Use --label <name>, repeat --id <profile-id>, and --yes as needed.

Label examples: codex-profiles label set --id <profile-id> --to work, codex-profiles label clear --label work.

Default examples: codex-profiles default set --label work, codex-profiles default show, codex-profiles default clear.

When load runs without a selector in a non-interactive session, it uses the saved default profile if one is set.

status --json returns the current profile object (or null); status --label/--id --json returns the selected saved profile object (or null when no saved profiles exist); status --all --json returns profiles plus hidden-profile counts.

export --output <file> exports all saved profiles by default. Use --label or repeated --id to export a smaller set.

Export bundles contain secrets. Store them securely. import fails on id, label, or default-profile conflicts instead of overwriting existing state.

When the exported set includes the current default profile, export/import preserves that default selection too.

doctor --fix repairs safe profile-storage metadata only (missing storage files, stale index/default refs, and a rebuild of profiles.json from saved profile files when needed). It does not delete invalid saved profile files in this first pass; when it rebuilds a broken profiles.json, it writes profiles.json.bak (or profiles.json.bak.N if a backup already exists), and labels/defaults stored only in the broken index may need to be reconfigured.

Warning

Deleting a profile does not log you out. It only removes the saved profile file.

Quick example:

$ codex-profiles save --label team
Saved profile [email protected] (Team)

$ codex-profiles load --label team
Loaded profile [email protected] (Team)

Note

Files are stored under ~/.codex/profiles/:

File	Purpose
{email-plan}.json	Saved profiles.
profiles.json	Profile metadata (labels and identity fields for saved profiles).
update.json	Cached updater state (latest checked version metadata).
profiles.lock	Lock file for safe updates.

FAQ

Is my auth file uploaded anywhere?

No. Everything stays on your machine. This tool only copies files locally.

What is a “profile” in this tool?

A profile is a saved copy of your ~/.codex/auth.json. Each profile represents one Codex login.

How do I save and switch between accounts?

Log in with Codex CLI, then run codex-profiles save --label <name>. To switch later, run codex-profiles load --label <name>.

What happens if I run load without saving?

You will be prompted to save the current profile, continue without saving, or cancel.

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?

After installing, verify it works:

# Check version
codex-profiles --version

# Verify the command runs
codex-profiles list
# Should show: "No saved profiles." if you have not saved any profiles yet

How do I verify a release?

See docs/verification.md for release manifests, checksums, and GitHub attestation verification steps.

Can I contribute to this project?

Yes! Contributions are welcome. For non-trivial changes (new features, significant refactors), please open an issue or discussion first to discuss your idea and avoid wasted effort.

For minor changes (bug fixes, typos, docs), feel free to submit a PR directly.

See CONTRIBUTING.md for full guidelines.