CLI reference

Run cmx --help or cmx <command> --help for the exact flags in your installed version. This page covers the normal workflow; <client> means one of codex, opencode, claude, aider, antigravity, or cline.

Setup and account

Command	Action
`cmx`	Open the terminal interface; use CONFIG to manage routing.
`cmx setup --ask-connect-ready`	Start the gateway and ask whether to connect detected, ready providers. Standalone installers use this mode.
`cmx setup --connect-ready`	Explicitly connect detected providers with available native credentials.
`cmx setup`	Start the gateway and discover providers; may connect Codex’s existing native sign-in.
`cmx login` / `cmx logout`	Sign in to or out of the optional CMX account. These do not sign in to your model provider.
`cmx dashboard`	Open the account-linked web dashboard.

For an installer prompt, y connects the listed ready providers. n or Enter keeps them direct, disables periodic auto-connect, and prints manual CLI and TUI instructions. If the terminal cannot accept input, setup returns an error; rerun cmx setup --ask-connect-ready in an interactive terminal.

Providers and client routing

cmx harness list
cmx providers codex list
cmx providers codex connect api
cmx providers codex disconnect api
cmx harness verify

Command	Action
`cmx providers [client] list`	Discover native provider IDs and readiness without changing routing.
`cmx providers <client> connect <id>`	Connect a selected native provider through CMX; starts the gateway if needed.
`cmx providers <client> disconnect <id>`	Restore that provider or client to direct routing.
`cmx providers <client> check <id>`	Check the selected provider.
`cmx providers <client> signin <id>`	Print the native sign-in guidance for that provider.
`cmx harness enable [client]`	Connect a detected client; with no client, acts on detected clients.
`cmx harness disable [client]`	Restore a detected client’s direct settings; with no client, acts on detected clients.
`cmx harness verify`	Check managed routes and report problems. Exits with an error if a client still points at a stopped gateway; run `cmx stop` to restore those clients to their direct connections. A real client request is still needed to prove traffic flows.

See Supported clients for connection IDs and readiness limits. The providers ID belongs to the client; it is not necessarily the same as CMX’s upstream provider ID.

Gateway and usage

Command	Action
`cmx start`	Start the local background gateway; may restore previously selected routes.
`cmx serve`	Run the gateway in the foreground.
`cmx status` / `cmx status --json`	Show gateway state, version, and active token metrics.
`cmx restart`	Gracefully restart the gateway daemon.
`cmx stop`	Restore managed clients to direct settings, then stop. Leaves gateway running if restoration fails.
`cmx autostart [enable\|disable\|status]`	Manage automatic gateway startup on system boot (systemd/launchd/Windows Run).
`cmx stats`	Show local usage and savings estimates.
`cmx doctor`	Run configuration, autostart, permissions, and connectivity checks.
`cmx selftest`	Run comprehensive runtime invariant checks (`INV-01` through `INV-16`).
`cmx pair [code\|status]`	Generate pairing codes or check pairing status with the web dashboard.
`cmx store [status\|vacuum]`	Inspect local SQLite database size, run maintenance, or optimize storage.
`cmx logs`	Explain the available diagnostics; CMX does not capture raw prompts or responses.
`cmx permissions [check\|fix]`	Check and enforce owner-only permissions on CMX files and directories.
`cmx sessions`	Inspect and delete stored local compression sessions. See Local sessions.
`cmx vault`	Inspect, export, or prune local lossless vault entries. See Content vault.

Local sessions

CMX stores each client conversation it routes as a local compression session. Use cmx sessions to review what CMX has kept, check how compression applied to a conversation, or remove stored history.

Command	Action
`cmx sessions list`	List recent sessions, newest first, with harness, provider, request, message, and token counts.
`cmx sessions list --limit=<N>`	Set how many sessions to list. Defaults to `50`; the maximum is `500`.
`cmx sessions list --harness=<name>`	Show only sessions from one client, such as `codex`, `opencode`, or `claude`.
`cmx sessions list --provider=<name>`	Show only sessions for one upstream provider.
`cmx sessions show <id>`	Print a session’s details, its compression records, and a short preview of each message.
`cmx sessions delete <id>`	Delete one session and the messages and compression records tied to it. `cmx sessions rm <id>` is an alias.
`cmx sessions purge`	Delete sessions that have not been updated within the local retention period (14 days by default). Also removes expired audit records and unused cached summaries.
`cmx sessions clear`	Delete every stored session and its related records.

You can combine the list filters:

cmx sessions list --harness=codex --provider=openai --limit=10

In cmx sessions show output, each compression record lists the replaced message range, the original and summary token estimates, and its status. A record marked credited counted toward your savings. A record marked cached covers content that an earlier record already credited, so CMX did not count it again.

cmx sessions delete and cmx sessions clear cannot be undone. They do not change your clients’ own conversation history.

Content vault

When the lossless content vault is enabled (compression.vault.enabled), CMX archives original text removed by tool pruning, error purging, or truncation into the local SQLite store. Use cmx vault to review, export, or trim archived items.

Command	Action
`cmx vault list`	List recent vault items, showing ID, kind, tool name, original token count, and creation time.
`cmx vault list --limit=<N>`	Set how many vault items to list. Defaults to `50`.
`cmx vault show <id>`	Show metadata and escaped original content of an archived vault item.
`cmx vault show <id> --raw`	Export raw original content bytes directly without terminal escaping.
`cmx vault delete <id>`	Delete an archived item from the vault by ID. `cmx vault rm <id>` is an alias.
`cmx vault clear`	Delete every item from the vault.
`cmx vault prune`	Prune oldest items to retain at most `compression.vault.max_entries` (default `10000`).
`cmx vault prune --keep=<N>`	Retain at most `<N>` newest items.

The vault is enabled by default (compression.vault.enabled: true) and stays strictly local to your machine. Vault contents are never sent to CMX Cloud.

Updates and removal

Command	Action
`cmx upgrade`	Check for a published update.
`cmx upgrade --install`	Download and install the latest verified release.
`cmx uninstall`	Restore clients, stop CMX, and remove local CMX files and executable.
`cmx uninstall --yes`	Run the same removal without an interactive confirmation.
`cmx uninstall --keep-data`	Keep local usage and session data.
`cmx uninstall --keep-config`	Keep CMX configuration.

cmx remove and cmx rm are aliases for cmx uninstall, and --force (-f) is an alias for --yes (-y).

See Undo and uninstall before removal. If you used npm or pnpm, remove the package registration separately after CMX restores clients.