CLI reference

Run Codex under any of your accounts from a terminal, bind folders to accounts, and manage Account Pool and your license. The codexuse command uses the same accounts and settings as the desktop app on the same machine.

Install

From the desktop app

The desktop app ships its own codexuse, always the same version as the app. Open Settings, go to codexuse in Terminal, and click Add codexuse to Terminal. Then open a new terminal and check it:

codexuse doctor

CodexUse writes ~/.codexuse/bin/codexuse and adds that folder to PATH for zsh, bash, and fish. For another shell, Settings shows the line to add. On Windows it adds the folder to your user Path. The command runs with the app's built-in runtime, so it needs no Node.js, and it updates with the app.

With npm, on a machine without the app

On an Intel Mac, a server, or over SSH, install the npm package. It needs Node.js 22.13 or later.

npm install -g codexuse-cli

If you later add the app's codexuse to the same machine, remove the npm copy with npm uninstall -g codexuse-cli. codexuse doctor tells you when both are installed, and codexuse --version says which copy runs.

Requirements

• The Codex CLI on your PATH. run, profile add, and profile refresh start it.
• For the npm package only: Node.js 22.13 or later, for its built-in SQLite.

Commands

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

codexuse profile list [--no-usage] [--compact]
codexuse profile current
codexuse profile cli <name> -- <codex args...>
codexuse profile switch <name>
codexuse profile add <name> [--skip-login] [--device-auth] [--login=browser|device]
codexuse profile refresh <name> [--skip-login] [--device-auth] [--login=browser|device]
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 account-pool status
codexuse account-pool quickstart
codexuse account-pool enable | disable
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|auto> [model-ids...]
codexuse account-pool reasoning <list|add|remove|reset> [values...]
codexuse account-pool fast <list|add|remove|reset> [values...]
codexuse account-pool keys <list|create|revoke> [id]
codexuse account-pool sessions list

Examples

codexuse profile list --compact
codexuse profile add Work --login=device
codexuse workspace bind Work
codexuse run -- --model gpt-6.1-sol
codexuse run --profile Personal --strict -- resume --last
codexuse profile switch Personal
codexuse account-pool quickstart
codexuse account-pool keys create
codexuse license status

What profile switch changes

codexuse profile switch <name> changes the sign-in that a plain codex uses in a terminal. It does not touch the Codex app: while the app has ~/.codex open, the command stops and asks you to switch in CodexUse instead. To run one command under another account without switching, use codexuse run --profile <name> -- or codexuse profile cli <name> --.

Account Pool from CLI Pro

Manage pooled accounts, published model names, and API keys without opening the desktop app.

codexuse account-pool status
codexuse account-pool profiles list
codexuse account-pool keys create
codexuse account-pool sessions list

• Settings, keys, and sessions are the ones the desktop app serves from.
• The base URL is shown in the app under Settings › Account Pool.

For Account Pool specifics, see the Account Pool docs.

Removed in 7.1

These commands repeated what the desktop app does. Each now prints what to use instead and exits with code 2.

• codexuse best: turn on Auto-roll in the app, or run one account with codexuse run --profile <name> --.
• codexuse profile autoroll: turn on Auto-roll in the app.
• --activate-codex, --no-activate-codex, --restart-codex, and --take-control on profile switch: switch the Codex app's account in CodexUse.
• --runtime and --state-dir on account-pool: the CLI always uses the app's Account Pool.

Notes

• run and profile cli bring the account's Codex settings up to date with ~/.codex/config.toml before Codex starts, the same as the app does.
• 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.
• In terminal/other clients, an account change usually applies on the next resumed/new turn, not mid-turn.
• On SSH/headless, sign-in defaults to device auth.
• License state is shared between the desktop app and CLI.
• Account Pool needs an active trial or Pro before it can serve requests.