Home › Docs › CLI reference

CLI reference

ReferenceUpdated Aug 2026 · 3 min read

Manage profiles, bind workspaces, run isolated Codex sessions, configure Accounts Pool, activate licenses, and sync encrypted settings from the terminal. The CLI shares state with the desktop app on the same machine.

Requirements

macOS, Windows, or Linux with Node 20 or later.
The Codex CLI on your PATH. profile add and profile refresh run codex login and fail without it.

The CLI is not the desktop app. There is no Windows or Linux desktop build, and none is in the current release line, so Codex App window control, thread handoff, and the rest of the desktop surface are macOS Apple Silicon only. From any terminal the CLI manages profiles, workspace bindings, Accounts Pool, licensing, and sync.

Install

Install manually: the codexuse command ships separately and is no longer bundled inside the desktop app.

Install with npm:

npm install -g codexuse-cli

Verify the install:

codexuse --version

Commands

codexuse doctor
codexuse run -- <codex args...>
codexuse run --profile <name> [--strict] -- <codex args...>
codexuse best [--dry-run] -- <codex args...>

codexuse profile list [--no-usage] [--compact]
codexuse profile current
codexuse profile cli <name> -- <codex args...>
codexuse profile add <name> [--skip-login] [--device-auth] [--login=browser|device]
codexuse profile refresh <name> [--skip-login] [--device-auth] [--login=browser|device]
codexuse profile switch <name> [--activate-codex]
codexuse profile autoroll [--switch-left=0-50] [--dry-run] [--watch] [--interval=seconds] [--activate-codex|--no-activate-codex]
codexuse profile delete <name>
codexuse profile rename <old> <new>

codexuse workspace bind <path> <profile>
codexuse workspace bind <profile>
codexuse workspace unbind [path]
codexuse workspace list
codexuse workspace status [path]

codexuse license status [--refresh]
codexuse license activate <license-key>

codexuse sync status
codexuse sync pull [--passphrase-stdin]
codexuse sync push [--passphrase-stdin]

codexuse account-pool status [--runtime=desktop] [--state-dir=/abs/path]
codexuse account-pool quickstart [--runtime=desktop] [--state-dir=/abs/path]
codexuse account-pool routing <least-used|round-robin>
codexuse account-pool profiles <list|set|add|remove|reset> [names...]
codexuse account-pool models <list|add|remove|reset> [model-ids...]
codexuse account-pool reasoning <list|add|remove|reset> [values...]
codexuse account-pool keys <list|create|revoke> [id]
codexuse account-pool sessions list [--runtime=desktop] [--state-dir=/abs/path]

Examples

codexuse profile list --compact
codexuse profile add Work --login=device
codexuse workspace bind Work
codexuse run -- --model gpt-5.3-codex
codexuse run --profile Personal --strict -- resume --last
codexuse profile switch Personal --activate-codex
codexuse profile autoroll --watch --interval=30 --switch-left=5
codexuse account-pool quickstart
codexuse account-pool keys create --runtime=desktop
codexuse license status

Accounts Pool from CLI Pro

Manage pooled profiles, exposed model names, and runtime keys without opening the desktop app.

codexuse account-pool status
codexuse account-pool profiles list
codexuse account-pool keys create
codexuse account-pool keys create --runtime=desktop
codexuse account-pool sessions list

Accounts Pool settings are shared with the desktop app on the same machine.
API keys and live sessions belong to the desktop app runtime store.
The plain account-pool keys create command mints a desktop key.

Cloud sync

Use sync commands when another machine needs the same profile metadata.

codexuse sync status shows sync state.
codexuse sync pull pulls profile metadata.
codexuse sync push pushes local changes.
Runs until you stop it with Ctrl+C or SIGTERM.
Use with a process manager (systemd, pm2, supervisord) for always-on setups.

For Accounts Pool specifics, see the Accounts Pool docs.

Cross-device handoff Pro

The common pattern: push from your main laptop, then pull on a second machine so your profiles and config are ready there.

# on the second machine
codexuse sync status
codexuse sync pull
codexuse profile list --compact

Notes

profile add and refresh run codex login (Codex CLI required).
workspace bind stores private local metadata; the nearest bound ancestor wins.
run uses the current workspace binding unless --profile overrides it; add --strict to reject a conflicting override.
Use --no-usage to skip live rate-limit fetch.
profile autoroll runs once by default; use --watch for continuous checks.
profile autoroll supports --dry-run to preview a switch without applying it.
In terminal/other clients, profile changes usually apply on the next resumed/new turn, not mid-turn.
On SSH/headless, login defaults to device auth.
License state is shared between the desktop app and CLI.
Accounts Pool API keys belong to the desktop app runtime store.
Cloud sync commands need an active trial or Pro and stay manual (no background auto-sync).
Accounts Pool needs an active trial or Pro before it can serve requests.