chatmux CLI

The Chatmux CLI reads and controls the Chatmux public API without a browser. The package has no browser-automation dependency. Interactive login may open the system browser; trajectory reads never use a browser.

Install

npm install --global chatmux

Authenticate

Sign in with the Chatmux browser flow:

chatmux auth login

The command opens https://chatmux.dev and waits for the browser confirmation. It stores a refresh token in ~/.config/chatmux/config.json with restrictive file permissions. Use --no-browser to print the URL without opening it. Press Ctrl-C to cancel the login. Use chatmux auth logout to remove the local session.

For headless automation, set CHATMUX_REFRESH_TOKEN and optionally CHATMUX_API_URL. API keys are still supported only for existing automation: use chatmux auth login --api-key cmux_sk_... or CHATMUX_API_KEY.

The CLI caches the short-lived access token beside the refresh token, so repeated commands skip the token-refresh round trip. The cache revalidates the token expiry locally and falls back to a refresh on any 401.

Call every platform operation

chatmux api list prints every operation in the Chatmux OpenAPI contract. chatmux api <operationId> calls any of them with typed parameters:

chatmux api list
chatmux api getThread --threadId t_abc123
chatmux api listSandboxes
chatmux api sendMessage --threadId t_abc123 --data '{"text":"hello"}'

This makes the CLI a complete debugging surface for the platform: whatever state Chatmux holds, an operation exposes it, and the CLI can call it. Account-scoped operations (preferences, notifications, message history) require a signed-in user session; API keys receive a 403 for those by design.

Manage Coderouter metadata

Coderouter commands require an explicitly selected organization:

chatmux auth login --org-id <organization-id>
chatmux coderouter status

For automation, set CHATMUX_REFRESH_TOKEN and CHATMUX_ORG_ID. Coderouter does not infer an organization from the current account and does not use the legacy API-key auth path.

The non-secret management surface is:

chatmux coderouter status
chatmux coderouter sources list
chatmux coderouter sources show <source-id>
chatmux coderouter sources add --adapter <id> --name <name> \
  --class <class> --auth-mode <mode> --custody <custody>
chatmux coderouter sources rename <source-id> --name <name>
chatmux coderouter sources repair <source-id>
chatmux coderouter sources remove <source-id>
chatmux coderouter routes list
chatmux coderouter routes add --name <name> --alias <alias> \
  --target <target-id> --operation <operation>
chatmux coderouter routes update <route-id> [options]
chatmux coderouter routes remove <route-id>
chatmux coderouter setup show <setup-session-id>
chatmux coderouter keys list
chatmux coderouter audit list

Add --json for one validated, recursively redacted JSON document. Management requests time out after 20 seconds by default; use --timeout-ms to choose a bound from 100 to 120000 milliseconds. Ctrl-C cancels the active request. Every mutation carries an Idempotency-Key; use --idempotency-key to repeat one deliberately, or let the CLI mint one.

sources add accepts metadata only. It never accepts a provider key, token, password, private key, or credential through arguments, environment variables, CLI config, or shell history. Sensitive custody belongs only in the protected, one-time browser setup flow under https://chatmux.dev/coderouter/connect.

coderouter status reads current feature availability from the server. The initial management slice reports source/route metadata controls available and provider adapters, the inference data plane, and route-key issuance unavailable. keys list returns metadata only; there is no key-create command. There are no Coderouter inference or relay commands in this package.

Read a full durable trajectory

chatmux trajectory https://chatmux.dev/t/<thread-id> --compact

The command reads the durable event log and the exact stored Pi session-tree entries through one authenticated NDJSON response, validates the stream, and writes one JSON document to stdout. Diagnostics and cancellation messages go only to stderr. The response header fixes both durable heads, so the command finishes even while the thread remains active. Live thinking text is not durable and is reported as not_persisted. A first Ctrl-C cancels and exits 130; a second Ctrl-C exits 130 immediately.

Compatibility

The public npm package intentionally installs only the chatmux executable. Legacy CLOUDMUX_* environment variables and the old read-only Cloudmux config location remain accepted as migration inputs. The private workspace CLI keeps a cloudmux executable alias for existing repository automation.