reference.md

Command Reference

Top-Level Commands

codex-profiles aliases

List configured alias mappings.

Examples:

codex-profiles aliases
codex-profiles aliases --json

codex-profiles list

List managed profiles.

Examples:

codex-profiles list
codex-profiles list --absolute
codex-profiles list --names

--names returns alias and profile names suitable for completion.

codex-profiles inspect <profile-or-alias>

Show resolved paths and metadata for one profile.

Examples:

codex-profiles inspect p2
codex-profiles inspect p4 --json

codex-profiles which [profile-or-alias]

Resolve the active or requested profile.

Examples:

codex-profiles which
codex-profiles which p3
codex-profiles which --json
codex-profiles which --shell

codex-profiles use <profile-or-alias>

Persist the current profile selection.

Examples:

codex-profiles use p2
codex-profiles use p1 --json
codex-profiles use p4 --shell

codex-profiles status

Show overall system state.

Examples:

codex-profiles status
codex-profiles status --json

codex-profiles doctor

Validate expected shared paths and symlinks.

Examples:

codex-profiles doctor
codex-profiles doctor p2
codex-profiles doctor --json

codex-profiles migrate

Preview or apply conservative shared-state migration.

Examples:

codex-profiles migrate
codex-profiles migrate --json
codex-profiles migrate --apply

codex-profiles run [profile-or-alias] -- [codex args...]

Run Codex with CODEX_HOME set for a resolved profile.

Examples:

codex-profiles run p2 -- login
codex-profiles run p3 -- resume --last
codex-profiles run -- resume --last

codex-profiles completion <zsh|bash>

Emit shell completion script.

Examples:

codex-profiles completion zsh
codex-profiles completion bash

codex-profiles install

Install local launcher and shell completion artifacts.

Examples:

codex-profiles install --print-only
codex-profiles install --shell zsh
codex-profiles install --shell bash

codex-profiles init

Create the shared root and optionally provision one profile.

Examples:

codex-profiles init
codex-profiles init --profile p2

codex-profiles add <profile-or-alias>

Provision a profile directory.

Examples:

codex-profiles add main
codex-profiles add p4

Compatibility Launcher

codex-profile

Thin convenience wrapper around codex-profiles run.

Examples:

codex-profile
codex-profile p2
codex-profile p3 login
codex-profile p4 resume --last

JSON-Capable Commands

These support --json:

• aliases
• inspect
• which
• use
• status
• doctor
• migrate

Selection Precedence

When no explicit profile argument is given:

1. explicit CLI profile argument
2. CODEX_PROFILE
3. persisted current profile from use
4. manifest default_profile

Concurrency Rules

Allowed:

• multiple simultaneous sessions on the same profile

Blocked:

• simultaneous sessions on different profiles