CodexUse CLI

Command-line control for CodexUse profiles: switch Codex accounts, run Codex under a chosen profile, and manage Account Pool, licenses, and manual cloud sync. Shares local state with the CodexUse desktop app on the same machine.

The CLI has a separate macOS, Windows, and Linux route. Codex App window control, provider setup, and the desktop Account Pool runtime require the Apple Silicon macOS desktop app. The CLI does not provide desktop feature parity.

Install (npm):

npm install -g codexuse-cli

Commands:

codexuse account-pool status [--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]

codexuse profile list
codexuse profile list --no-usage
codexuse profile list --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|--no-activate-codex] [--take-control]
codexuse profile autoroll [--switch-left=0-50] [--dry-run] [--watch] [--interval=seconds] [--activate-codex|--no-activate-codex] [--take-control]
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 run -- <codex args...>
codexuse run --profile <name> -- <codex args...>
codexuse run --profile <name> --strict -- <codex args...>

codexuse license status
codexuse license activate <license-key>

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

Notes:

• Requires Codex CLI on PATH for profile add / refresh (runs codex login in an isolated temporary home).
• Custom-provider profiles — a profile that runs a non-OpenAI model inside the Codex App — appear in profile list and profile current; profile switch and run accept them.
• A custom-provider profile reads not metered instead of rate-limit usage: it uses no OpenAI quota and you pay your provider directly.
• Create provider connections and models in the desktop app under Settings → Model Providers. The CLI does not create them. Reference: https://codexuse.com/docs/providers/
• profile cli runs Codex in the profile's permanent isolated home without changing the active global login.
• workspace bind stores private machine-local path bindings; run selects the nearest bound ancestor.
• run --profile warns when it overrides a binding; add --strict to reject mismatches.
• profile list reads live rate-limit usage via Codex CLI by default.
• Use --no-usage to skip rate-limit fetch.
• Cloud Sync uses a saved Keychain passphrase, CODEXUSE_SYNC_PASSPHRASE, or --passphrase-stdin.
• Use --compact for names only.
• On headless/SSH, login defaults to device auth. Override with --login=browser.
• Use --skip-login if you already ran codex login.
• Account Pool settings are shared with the desktop app on the same machine.
• Account Pool API keys and live sessions belong to the desktop app runtime store.
• profile autoroll requires Pro or an active trial.
• profile autoroll uses live rate-limit usage and switches when current remaining usage is at or below the % left threshold.
• profile autoroll defaults to saved desktop auto-roll switch threshold when available (else 5% left).
• Use --switch-left=NN to set the switch threshold by percent left.
• Profile switches synchronize an already-running managed ChatGPT/Codex app by default without launching a closed app.
• If that app is generating, the command waits for its completion event and then finishes synchronization without polling.
• --activate-codex also launches a closed app; --no-activate-codex disables app synchronization.
• --take-control explicitly permits verified replacement of an unmanaged app window.
• profile autoroll --watch keeps polling at --interval seconds (default 30).