Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(cua-cli): add a reference section for the cua CLI (#3122)

r33drichards0027ee679948
diff --git a/docs/content/docs/reference/cua-cli/authentication.mdx b/docs/content/docs/reference/cua-cli/authentication.mdx
new file mode 100644
index 0000000000..c7c697117b
--- /dev/null
+++ b/docs/content/docs/reference/cua-cli/authentication.mdx
@@ -0,0 +1,276 @@
+---
+title: Authentication
+description: 'How the cua CLI logs in, where it stores tokens, how to authenticate on a headless host, and which environment variables take effect.'
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+`cua` authenticates with OAuth device authorization. Endpoints are discovered
+from the issuer `https://auth.cua.ai/realms/cyclops-cs`; authenticated cloud
+requests then go to `https://run.cua.ai`.
+
+## Logging in
+
+```bash
+cua auth login
+```
+
+The CLI prints a verification URL and a user code, tries to open a browser, and
+then polls until you approve. Because the code is printed, the flow works over
+SSH and in terminals with no browser at all — pass `--no-browser` to skip the
+browser attempt entirely:
+
+```console
+$ cua auth login --no-browser
+Open this URL in any browser:
+https://auth.cua.ai/realms/cyclops-cs/device?user_code=QYNE-RIGM
+Enter this code if prompted: QYNE-RIGM
+```
+
+Approve in any browser, on any machine, then return to the terminal. Check the
+result at any time:
+
+```console
+$ cua auth status
+Logged in to run.cua.ai. Access token expires 2026-08-12T22:36:31.604247+00:00.
+```
+
+Access tokens are refreshed automatically before authenticated requests, so the
+expiry shown by `cua auth status` moves forward on its own. `cua auth logout`
+asks the issuer to revoke the refresh token and removes the local credentials
+either way, even if the network is unavailable. The CLI never prints access or
+refresh tokens.
+
+## Where credentials are stored
+
+Tokens go into the operating system credential vault through the `keyring`
+library, under service `run.cua.ai` and account `cua-cli`. The CLI does not read
+an API key from the environment and does not write one to a `.env` file.
+
+That vault is macOS Keychain, Windows Credential Manager, or — on Linux — a
+Secret Service provider such as `gnome-keyring` or KWallet. A server typically
+has none of these.
+
+## Headless hosts
+
+On a Linux host with no keyring backend, `keyring` falls back to
+`keyring.backends.fail.Keyring` and every credential operation raises:
+
+```console
+$ cua auth login --no-browser
+Open this URL in any browser:
+https://auth.cua.ai/realms/cyclops-cs/device?user_code=BCOP-JOSP
+Enter this code if prompted: BCOP-JOSP
+Error: Login failed: No secure credential store is available.
+Configure an OS keyring before logging in.
+```
+
+Two things are worth knowing about this failure. It happens **after** you have
+already approved in the browser, because the store is only written once the
+device flow completes — so the approval is wasted and has to be repeated. And it
+is not limited to `login`: `cua auth status` and every authenticated command
+raise the same error, because reading the vault fails the same way writing does.
+
+<Callout type="warn">
+ **What is at stake is a refresh token, not just an access token.** The stored
+ credential re-mints access tokens on demand, so it stays useful long after any
+ access token it produced has expired, and automatic refresh keeps rewriting it
+ so it never goes stale on its own. Whoever reads it holds your Cua session
+ until it is revoked. Choose the storage backend accordingly, and prefer an
+ encrypted one wherever the host outlives the job.
+</Callout>
+
+### Option 1: an encrypted file keyring
+
+The best fit for most headless hosts. `keyrings.cryptfile` writes to a file like
+the other file-backed backends but encrypts the store with a passphrase (Argon2
+key derivation, AES-GCM):
+
+```bash
+pip install keyrings.cryptfile
+export PYTHON_KEYRING_BACKEND=keyrings.cryptfile.cryptfile.CryptFileKeyring
+cua auth login --no-browser
+```
+
+The store lives at `~/.local/share/python_keyring/cryptfile_pass.cfg`, mode
+`600`. Every command that touches credentials prompts once for the passphrase:
+
+```console
+$ cua auth status
+Please enter password for encrypted keyring:
+Logged in to run.cua.ai. Access token expires 2026-08-12T22:36:31.604247+00:00.
+```
+
+That prompt is the tradeoff: fine for a host you log into and work on,
+unworkable for an unattended job.
+
+`keyrings.alt` also ships an `EncryptedKeyring`, which stores to
+`crypted_pass.cfg` at mode `600` and prompts the same way. It needs a crypto
+library that `keyrings.alt` does not itself install, so add it explicitly or the
+backend fails to load with `ModuleNotFoundError: No module named 'Crypto'`:
+
+```bash
+pip install keyrings.alt pycryptodome
+export PYTHON_KEYRING_BACKEND=keyrings.alt.file.EncryptedKeyring
+```
+
+### Option 2: a plaintext file keyring, for hosts that are thrown away
+
+Use this only where the machine is destroyed after the job — a CI runner, an
+ephemeral VM — and never on anything that persists.
+
+```bash
+pip install keyrings.alt
+export PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring
+cua auth login --no-browser
+```
+
+Or install it alongside the CLI in one step:
+
+```bash
+uv tool install cua-cli --with keyrings.alt --index https://wheels.cua.ai/simple
+```
+
+Credentials then land in **`~/.local/share/python_keyring/keyring_pass.cfg`**,
+created with mode `600`. That is the file to protect, and the file to delete
+when you are finished with a host that outlived its purpose — removing it, or
+running `cua auth logout`, is what actually gets the credential off the disk.
+
+Setting `PYTHON_KEYRING_BACKEND` is not strictly required — `PlaintextKeyring`
+registers at a higher priority than the failing backend, so `keyring` selects it
+on its own once installed. Set it anyway: it pins the choice, so installing
+another backend later cannot silently move where your tokens are kept.
+
+<Callout type="warn">
+ **`PlaintextKeyring` does not encrypt anything.** Values are base64-encoded,
+ which is an encoding and not a protection — anyone who can read the file can
+ recover the token with one command. File permissions are the only real barrier,
+ and they do not survive a backup, a snapshot, a stray `tar`, or another user
+ with root. Prefer Option 1 whenever the host persists.
+</Callout>
+
+### Option 3: a real keyring
+
+On a persistent Linux server, install and unlock a Secret Service provider such
+as `gnome-keyring` and let the default backend find it. This keeps the CLI on
+the same storage path it uses on a desktop, at the cost of having to unlock the
+keyring for each session — with `dbus-run-session` or a PAM module, depending on
+how the host is administered.
+
+### Option 4: do not log in at all
+
+For CI, skip the interactive session and hand the CLI a workload token instead.
+See [GitHub Actions](#github-actions) below.
+
+## Environment variables
+
+The CLI itself reads only these:
+
+| Variable | Effect |
+|----------|--------|
+| `FLEETS_TOKEN` | Fleet workload token. When set, it takes precedence over the interactive session for Fleet operations. |
+| `CUA_MCP_PERMISSIONS` | Default permission list for `cua serve-mcp`, overridden by `--permissions`. |
+| `CUA_SANDBOX` | Default sandbox for MCP computer tools, overridden by `--sandbox`. |
+| `ANTHROPIC_API_KEY` | Used by `cua do snapshot` and by `cua skills record --provider anthropic`. |
+| `OPENAI_API_KEY` | Used by `cua skills record --provider openai`. |
+| `PYTHON_KEYRING_BACKEND` | Read by the `keyring` library to select where credentials are stored. |
+| `XDG_DATA_HOME`, `XDG_STATE_HOME` | Move `~/.local/share/cua` and `~/.local/state/cua`. |
+
+The Sandbox SDK reads a further set. These apply when you import `cua_sandbox`
+in your own code:
+
+| Variable | Effect |
+|----------|--------|
+| `CUA_API_KEY` | API key for cloud sandboxes. |
+| `CUA_BASE_URL` | Base URL for the older VM API. Its default, `https://api.cua.ai`, is a retired host — set this explicitly if you use that API. |
+| `CUA_FLEET_BASE_URL` | Base URL for the Fleet API. Defaults to `https://run.cua.ai`. |
+| `CUA_TOKEN_URL` | OAuth token endpoint for client-credentials auth. |
+| `CUA_CLIENT_ID`, `CUA_CLIENT_SECRET` | OAuth client credentials for Fleet. |
+| `FLEETS_TOKEN` | Static Fleet workload token, checked before client credentials. |
+
+<Callout type="info">
+ `CUA_BASE_URL` has no effect on `cua` commands. The CLI overwrites it at
+ startup so that cloud requests always go to `https://run.cua.ai`, whatever the
+ environment says. Set it only for direct SDK use.
+</Callout>
+
+Fleet requests — the `--pool` path and everything `cua wif-token` feeds — go to
+`CUA_FLEET_BASE_URL`, which defaults to `https://run.cua.ai` and is the current
+cloud API. `CUA_BASE_URL` addresses the older VM API instead, and its default
+host is retired.
+
+<Callout type="warn">
+ **`CUA_API_KEY` is not a way to skip logging in, and setting it makes things
+ worse rather than better.** The SDK picks its transport with
+ `_uses_fleet(api_key)`, which is true only when **no** API key is supplied. So
+ providing one routes the call away from Fleet and onto the older VM API —
+ whose host is retired — and it will fail there no matter how valid the key is.
+ `FLEETS_TOKEN` is the environment variable that actually reaches a working
+ API.
+</Callout>
+
+`CUA_API_KEY` is not an authentication path for the CLI either: `cua` passes its
+own session token explicitly on every cloud call, and an explicitly passed key
+takes precedence over the environment.
+
+## Fleet pools need their own credentials
+
+`cua auth login` covers the CLI's own cloud calls, but it does not cover Fleet.
+`cua sb launch --pool` invokes the SDK without passing the interactive session
+through, and the SDK resolves Fleet credentials only from `FLEETS_TOKEN`, or
+from `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET`. With a perfectly valid session and
+none of those exported, the command fails:
+
+```console
+$ cua sb launch --pool my-pool --name my-sandbox
+Error: Fleet cloud sandboxes require CUA_CLIENT_ID and CUA_CLIENT_SECRET, or cua.configure(client_id=..., client_secret=...).
+```
+
+`cua auth status` still reports a live session at that point, so the message is
+easy to misread as an authentication failure. It is not — it is a different
+credential for a different API. Export a client id and secret for interactive
+use, or use `cua wif-token github` in CI:
+
+```bash
+export CUA_CLIENT_ID=...
+export CUA_CLIENT_SECRET=...
+cua sb launch --pool my-pool --name my-sandbox
+```
+
+## GitHub Actions
+
+`cua wif-token github` exchanges the job's GitHub OIDC identity for a Fleets
+token. It runs only inside GitHub Actions, requests the `fleets` audience, and
+prints nothing but the raw token:
+
+```console
+$ cua wif-token github
+Error: ACTIONS_ID_TOKEN_REQUEST_URL is missing; run in GitHub Actions with permissions: id-token: write.
+```
+
+The job needs `id-token: write`. `FLEETS_TOKEN` is process-scoped and ephemeral;
+while it is set, it takes precedence over any interactive session:
+
+```yaml
+permissions:
+ id-token: write
+ contents: read
+
+steps:
+ - name: Run a non-interactive Fleets sandbox
+ run: |
+ export FLEETS_TOKEN="$(cua wif-token github)"
+ cua sb launch ghcr.io/trycua/mini-swe:latest --name sandbox
+ cua sb exec sandbox -- pwd
+ cua sb delete sandbox --force
+```
+
+Use the GitHub-authorized sandbox name `sandbox`. `cua sb delete sandbox --force`
+releases the claim while preserving the reconciled one-replica pool, template,
+and namespace for the next claim.
+
+<Callout type="info">
+ Under `FLEETS_TOKEN`, `cua sb ls` exits with
+ `Listing Fleet sandboxes is not supported; use 'cua sb info NAME'.` Address
+ Fleet sandboxes by name.
+</Callout>
diff --git a/docs/content/docs/reference/cua-cli/cli-reference.mdx b/docs/content/docs/reference/cua-cli/cli-reference.mdx
new file mode 100644
index 0000000000..7fc51fedc9
--- /dev/null
+++ b/docs/content/docs/reference/cua-cli/cli-reference.mdx
@@ -0,0 +1,595 @@
+---
+title: CLI reference
+description: 'Command reference for the cua CLI: authentication, sandboxes, images, platforms, one-shot automation, skills, and trajectories.'
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+`cua` is the unified command-line interface for Cua. It authenticates against
+Cua cloud, manages sandboxes and images, drives a running machine one command at
+a time, and serves an MCP endpoint for AI assistants.
+
+Documented against `cua-cli` **0.1.14**. Run `cua --version` for your installed
+version, and `cua <command> --help` for the options your build accepts.
+
+## Install
+
+The CLI is published to Cua's own wheel index, so the index must be passed on
+the install command:
+
+```bash
+pip install --extra-index-url https://wheels.cua.ai/simple cua-cli
+```
+
+Optional extras add the MCP server (`mcp`), skill recording with VLM captioning
+(`skills`), or both (`all`):
+
+```bash
+pip install --extra-index-url https://wheels.cua.ai/simple "cua-cli[all]"
+```
+
+To keep the CLI isolated from your project environments, install it as a tool:
+
+```bash
+uv tool install cua-cli --index https://wheels.cua.ai/simple
+```
+
+<Callout type="warn">
+ On a headless Linux host, add a keyring backend at install time or the first
+ authenticated command will fail. See
+ [Authentication](/reference/cua-cli/authentication#headless-hosts).
+</Callout>
+
+## Conventions
+
+Several command groups have short aliases, and some subcommands have their own:
+
+| Canonical | Alias |
+|-----------|-------|
+| `cua sandbox` | `cua sb` |
+| `cua image` | `cua img` |
+| `cua trajectory` | `cua traj` |
+| `cua sb ls` | `cua sb list` |
+| `cua sb info` | `cua sb get` |
+| `cua image list` | `cua image ls` |
+| `cua skills list` | `cua skills ls` |
+
+Most commands that produce structured data accept `--json`. Two take
+`--format json` instead: `cua platform list`, and `cua image list` when it is
+listing local images. Commands that act on a machine take `--local` to target a
+local sandbox rather than a cloud one.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success. Also returned by bare `cua`, which prints help. |
+| `1` | The command ran and failed. The reason is printed as `Error: ...`. |
+| `2` | Argument parsing failed. `argparse` prints the usage line and the offending value. |
+
+## Global options
+
+| Option | Description |
+|--------|-------------|
+| `-h, --help` | Show help for the CLI or for any subcommand. |
+| `-v, --version` | Print the installed `cua-cli` version and exit. |
+
+## `cua auth`
+
+Manage the Cua cloud session. Tokens are stored in the operating system
+credential vault, never in a file the CLI writes itself.
+
+| Command | Description |
+|---------|-------------|
+| `cua auth login` | Log in through OAuth device authorization. |
+| `cua auth logout` | Revoke the refresh token and remove local credentials. |
+| `cua auth status` | Report whether a session exists and when its access token expires. |
+
+`cua auth login` takes one flag:
+
+| Option | Description |
+|--------|-------------|
+| `--no-browser` | Print the verification URL instead of trying to open a browser. |
+
+```console
+$ cua auth status
+Logged in to run.cua.ai. Access token expires 2026-08-12T22:36:31.604247+00:00.
+```
+
+See [Authentication](/reference/cua-cli/authentication) for the device flow, the
+headless-host workaround, and the environment variables the SDK reads.
+
+## `cua sandbox`
+
+Create and control sandboxes, cloud or local. Aliased as `cua sb`.
+
+<Callout type="warn">
+ **There are two different cloud paths behind these commands, and only one of
+ them is current.** Passing `--pool` claims a sandbox from a Fleet pool, which
+ is the supported cloud path. Passing an image without `--pool` goes through
+ the older VM API, whose host `api.cua.ai` has been retired; those routes now
+ live elsewhere and the CLI has not been repointed at them, so image-based
+ cloud launches do not work today. Use `--pool` for cloud work, or `--local`
+ for a sandbox on your own machine.
+</Callout>
+
+### `cua sb launch`
+
+Launch a new sandbox. Exactly one of the positional image or `--pool` is
+required; passing both, or neither, is an error.
+
+**Arguments:**
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `<image>` | No | Image to launch, for example `macos`, `ubuntu:24.04`, `windows:11`, or a registry reference such as `ghcr.io/trycua/mini-swe:latest`. |
+
+**Options:**
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `--pool` | — | Claim the named pre-created Fleet pool instead of launching an image. Requires `--name`. |
+| `--local` | false | Launch a local sandbox. Requires a working local runtime. |
+| `--name` | generated | Sandbox name. |
+| `--vm` | false | Force VM kind for Linux images. Linux defaults to a container. |
+| `--cpu` | — | Number of vCPUs. |
+| `--memory` | — | Memory, as `8GB` or `4096MB`. A bare number is read as GB. |
+| `--disk` | — | Disk size, as `50GB`. A bare number is read as GB. |
+| `--region` | — | Cloud region. |
+| `--json` | false | Print `{"name": ..., "status": "ready"}` instead of a status line. |
+
+Bare image names are expanded before the request is made:
+
+| You write | You get |
+|-----------|---------|
+| `linux`, `ubuntu`, `debian`, `fedora` | Linux container, defaulting to Ubuntu 24.04 |
+| `windows`, `win` | Windows, defaulting to `2022` |
+| `macos`, `mac`, `osx` | macOS, defaulting to `26` |
+| `android` | Android, defaulting to `14` |
+| Anything with a registry host, such as `ghcr.io/org/image` | Pulled from that registry |
+
+A tag after a colon overrides the default version, so `ubuntu:22.04`,
+`windows:11`, and `macos:sequoia` all work.
+
+<Callout type="warn">
+ **`--pool` needs Fleet credentials in the environment; logging in is not
+ enough.** Every other cloud command reuses your `cua auth login` session, but
+ the Fleet path does not pass that session through. Without either
+ `FLEETS_TOKEN` or a `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET` pair exported,
+ `cua sb launch --pool` fails with:
+
+ ```
+ Error: Fleet cloud sandboxes require CUA_CLIENT_ID and CUA_CLIENT_SECRET, or cua.configure(client_id=..., client_secret=...).
+ ```
+
+ This is easy to misread as "you are not logged in" when `cua auth status`
+ cheerfully reports a valid session. Export the credentials, or use
+ `cua wif-token github` in CI, before reaching for `--pool`.
+</Callout>
+
+### `cua sb ls`
+
+List sandboxes. With no flags, lists cloud sandboxes.
+
+| Name | Description |
+|------|-------------|
+| `--local` | List local sandboxes. |
+| `--all` | List both local and cloud sandboxes. |
+| `--json` | Output as JSON. |
+
+```console
+$ cua sb ls --local
+┏━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+┃ NAME ┃ STATUS ┃ SOURCE ┃
+┡━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
+│ mc-win │ running │ qemu-baremetal │
+│ linux-demo │ running │ docker │
+└─────────────┴─────────┴────────────────┘
+```
+
+The `SOURCE` column names the runtime backing each sandbox — `docker`,
+`qemu-baremetal`, `lume`, or `cloud`.
+
+<Callout type="warn">
+ **There is no way to list cloud sandboxes, and no configuration that enables
+ it.** Fleet has no list operation at all — with `FLEETS_TOKEN` set, `cua sb ls`
+ refuses outright with `Listing Fleet sandboxes is not supported; use 'cua sb
+ info NAME'.` Without it, the listing falls to the retired VM API described
+ above and cannot succeed either. Address cloud sandboxes by name with
+ `cua sb info`. `--local` is unaffected and lists normally.
+</Callout>
+
+Older versions report this as `No sandboxes found.` rather than as an error,
+because the cloud listing swallowed its exception — so on those versions an
+empty cloud list is indistinguishable from a failure. Either way, an empty cloud
+list is not evidence that the account has no sandboxes.
+
+### `cua sb info`
+
+Show a sandbox's name, status, and — when the provider reports them — OS, host,
+region, and creation time. Aliased as `cua sb get`.
+
+| Name | Description |
+|------|-------------|
+| `<name>` | Sandbox name. Required. |
+| `--local` | Target a local sandbox. |
+| `--json` | Output as JSON. |
+
+### Lifecycle commands
+
+Each takes a sandbox name and an optional `--local`:
+
+| Command | Description |
+|---------|-------------|
+| `cua sb suspend <name>` | Suspend the sandbox, preserving memory state. |
+| `cua sb resume <name>` | Resume a suspended sandbox. |
+| `cua sb restart <name>` | Restart the sandbox. |
+| `cua sb vnc <name>` | Open the sandbox's display in a browser. |
+
+### `cua sb delete`
+
+Delete a sandbox.
+
+| Name | Description |
+|------|-------------|
+| `<name>` | Sandbox name. Required. |
+| `--local` | Target a local sandbox. |
+| `--force` | Skip the confirmation prompt. |
+
+The prompt is also skipped automatically when stdin is not a terminal, so a
+piped or CI invocation deletes without `--force`. Pass it anyway to make the
+intent explicit.
+
+### `cua sb shell`
+
+Open an interactive shell in the sandbox, or run a single command with a TTY
+attached. Everything after the sandbox name is passed through.
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `<name>` | — | Sandbox name. Required. |
+| `<command…>` | — | Command to run. Omit for an interactive shell. |
+| `--local` | false | Target a local sandbox. |
+| `--cols` | auto-detect | Terminal width. |
+| `--rows` | auto-detect | Terminal height. |
+
+### `cua sb exec`
+
+Run a command non-interactively and exit. Use `--` before the command so its
+own flags are not parsed by `cua`.
+
+```bash
+cua sb exec my-sandbox -- pwd
+```
+
+| Name | Description |
+|------|-------------|
+| `<name>` | Sandbox name. Required. |
+| `<command…>` | Command to execute. |
+| `--local` | Target a local sandbox. |
+| `--json` | Output as JSON. |
+
+## `cua image`
+
+Manage images. Cloud images live in your Cua workspace; local images live under
+`~/.local/share/cua/images/`. Aliased as `cua img`.
+
+### `cua image list`
+
+List images. Cloud is the default. Aliased as `cua image ls`.
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `--cloud` | true | List cloud images. |
+| `--local` | false | List local images. |
+| `--platform` | — | Filter local images by platform. |
+| `--format` | `table` | Output format for local images: `table` or `json`. |
+| `--json` | false | Output cloud images as JSON. |
+
+### `cua image push`
+
+Upload a local image file to cloud storage.
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `<name>` | — | Image name. Required. |
+| `--file`, `-f` | `~/.local/share/cua/images/<name>/data.img` | Path to the image file. |
+| `--tag` | `latest` | Image tag. |
+| `--type` | `qcow2` | Image type: `qcow2`, `raw`, or `vmdk`. |
+
+### `cua image pull`
+
+Download an image from cloud storage.
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `<name>` | — | Image name. Required. |
+| `--tag` | `latest` | Image tag. |
+| `--output`, `-o` | — | Output file path. |
+
+### `cua image delete`
+
+Delete an image. Cloud by default.
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `<name>` | — | Image name. Required. |
+| `--tag` | `latest` | Image tag, for cloud images. |
+| `--local` | false | Delete a local image instead. |
+| `--force` | false | Skip confirmation. |
+
+### `cua image create`
+
+Build a local image from a platform definition. See
+[`cua platform`](#cua-platform) for the platform list and each one's
+requirements.
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `<platform>` | — | Platform name, for example `linux-docker` or `windows-qemu`. Required. |
+| `--name` | same as platform | Image name. |
+| `--iso` | — | Path to an ISO, for QEMU platforms. |
+| `--download-iso` | false | Download the Windows 11 ISO (~6 GB). |
+| `--docker-image` | platform default | Override the Docker image. |
+| `--distro` | `ubuntu` | Linux distribution: `ubuntu` or `fedora`. |
+| `--version` | `14` | OS version, for example `14` for Android or `sonoma` for macOS. |
+| `--disk` | `64G` | Disk size. |
+| `--memory` | `8G` | Memory. |
+| `--cpus` | `8` | CPU cores. |
+| `--winarena-apps` | false | Install the WinArena benchmark apps. |
+| `--detach`, `-d` | false | Run in the background. |
+| `--force` | false | Recreate an existing image. |
+| `--skip-pull` | false | Do not pull the Docker image. |
+| `--no-kvm` | false | Disable KVM acceleration. |
+| `--vnc-port` | auto from 8006 | VNC port. |
+| `--api-port` | auto from 5000 | API port. |
+
+### Local image commands
+
+| Command | Description |
+|---------|-------------|
+| `cua image info <name>` | Show a local image's details. |
+| `cua image clone <source> <target>` | Clone a local image. Add `--force` to overwrite the target. |
+| `cua image shell <name>` | Boot the image and open a shell in it. |
+
+`cua image shell` writes to a disposable overlay by default:
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `--writable` | false | Modify the golden image directly. Destructive. |
+| `--detach`, `-d` | false | Run in the background. |
+| `--memory` | `8G` | Memory. |
+| `--cpus` | `8` | CPU cores. |
+| `--no-kvm` | false | Disable KVM acceleration. |
+| `--vnc-port` | auto from 8006 | VNC port. |
+| `--api-port` | auto from 5000 | API port. |
+
+## `cua platform`
+
+Inspect the platform definitions `cua image create` can build from, and whether
+this host meets their requirements.
+
+| Command | Description |
+|---------|-------------|
+| `cua platform list` | List platforms with their status on this host. Accepts `--format table\|json`. Also the default when `cua platform` is run bare. |
+| `cua platform info <platform>` | Show a platform's Docker image, ports, KVM requirement, and boot timeout. |
+
+```console
+$ cua platform list
+
+Platforms
+================================================================================
+
+System:
+ Docker: ✗ Not running
+ KVM: ✓ Available
+
+--------------------------------------------------------------------------------
+
+PLATFORM DESCRIPTION STATUS
+--------------------------------------------------------------------------------
+linux-docker Linux GUI container (no KVM required) no Docker
+linux-qemu Linux VM with QEMU/KVM (OSWorld) no Docker
+windows-qemu Windows VM with QEMU/KVM (Windows Arena) no Docker
+android-qemu Android VM with QEMU/KVM no Docker
+macos-lume macOS VM with Apple Virtualization (Lume, Ap macOS only
+```
+
+Every platform except `macos-lume` runs through Docker, so a host without Docker
+reports `no Docker` for all of them regardless of KVM. `macos-lume` requires an
+Apple Silicon Mac running [Lume](/reference/lume/cli-reference).
+
+## `cua do`
+
+Send one automation command to a target machine and exit. `cua do` keeps a
+selected target in `~/.cua/do_target.json`, so the target survives between
+invocations.
+
+Output is a single line beginning with `✅` or `❌`, followed by a context line
+showing the current machine and zoom state. Coordinates are in screenshot-image
+space; when a zoom is active the CLI translates them for you.
+
+| Option | Description |
+|--------|-------------|
+| `--no-record` | Disable trajectory recording for this command. Goes before the action: `cua do --no-record status`. |
+
+### Target selection
+
+| Command | Description |
+|---------|-------------|
+| `cua do switch <provider> [name]` | Select the target. Providers: `cloud`, `cloudv2`, `local`, `lume`, `lumier`, `docker`, `winsandbox`, `host`. |
+| `cua do ls [provider]` | List machines for one provider. With no provider, lists the host plus every local and cloud sandbox. |
+| `cua do status` | Show the current target and zoom state. |
+| `cua do-host-consent` | Grant consent for `cua do switch host` and switch to it. |
+
+`host` means your own desktop. Selecting it is refused until consent is granted:
+
+```console
+$ cua do switch host
+❌ Warning: you are about to allow an AI to control your host PC directly.
+ This grants full keyboard, mouse, and screen access to your local desktop.
+ To continue, please run: cua do-host-consent
+```
+
+<Callout type="warn">
+ `cua do-host-consent` is a top-level command, not a subcommand of `cua do`, and
+ it writes a persistent marker at `~/.cua/host_consented`. Consent stays granted
+ until that file is removed.
+</Callout>
+
+### Screen and framing
+
+| Command | Description |
+|---------|-------------|
+| `cua do screenshot [--save PATH]` | Capture the screen. Saved to a temp directory unless `--save`/`-s` is given. |
+| `cua do snapshot [instructions…]` | Screenshot plus an AI summary of the screen and its interactive elements. Requires `ANTHROPIC_API_KEY`. |
+| `cua do zoom <window-name>` | Crop every subsequent screenshot to that window and translate coordinates into it. |
+| `cua do unzoom` | Return to full-screen screenshots. |
+
+### Input
+
+| Command | Description |
+|---------|-------------|
+| `cua do click <x> <y> [left\|right\|middle]` | Click. Defaults to `left`. |
+| `cua do dclick <x> <y>` | Double-click. |
+| `cua do move <x> <y>` | Move the cursor. |
+| `cua do drag <x1> <y1> <x2> <y2>` | Drag between two points. |
+| `cua do type <text>` | Type text. |
+| `cua do key <key>` | Press one key, such as `enter`, `escape`, or `tab`. |
+| `cua do hotkey <combo>` | Press a shortcut, such as `cmd+c` or `ctrl+shift+s`. |
+| `cua do scroll <up\|down\|left\|right> [amount]` | Scroll. Amount defaults to `3`. |
+
+### Shell and files
+
+| Command | Description |
+|---------|-------------|
+| `cua do shell [command…]` | Run a shell command in the target, or open an interactive terminal when no command is given. Accepts `--cols` and `--rows`. |
+| `cua do open <path-or-url>` | Open a file or URL in the target. |
+
+### Windows
+
+| Command | Description |
+|---------|-------------|
+| `cua do window ls [app]` | List windows, optionally filtered by application. |
+| `cua do window focus <id>` | Focus a window. `activate` is accepted as well. |
+| `cua do window unfocus` | Remove focus from the current window. |
+| `cua do window minimize\|maximize\|close <id>` | Change a window's state. |
+| `cua do window resize <id> <width> <height>` | Resize a window. |
+| `cua do window move <id> <x> <y>` | Move a window. |
+| `cua do window info <id>` | Show a window's details. |
+
+## `cua skills`
+
+Record demonstrations on a sandbox and keep them as skills for agents to follow.
+Skills are stored in `~/.cua/skills/`.
+
+| Command | Description |
+|---------|-------------|
+| `cua skills list` | List saved skills. Accepts `--json`. Aliased as `cua skills ls`. |
+| `cua skills read <name>` | Print a skill. `--format`/`-f` selects `md` (default) or `json`. |
+| `cua skills replay <name>` | Open the skill's video recording. |
+| `cua skills delete <name>` | Delete one skill. |
+| `cua skills clean` | Delete every skill, after confirmation. |
+
+### `cua skills record`
+
+Connect to a machine, record what you do, and caption the result with a vision
+model. Requires the `skills` extra.
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `--sandbox`, `-s` | — | Sandbox name to connect to. |
+| `--vnc-url`, `-u` | — | Connect to a VNC URL directly instead. |
+| `--provider`, `-p` | `anthropic` | Captioning provider: `anthropic` or `openai`. |
+| `--model`, `-m` | provider default | Captioning model. |
+| `--api-key`, `-k` | from environment | API key for the captioning provider. |
+| `--name`, `-n` | prompted | Skill name. Supplying it skips the prompt. |
+| `--description`, `-d` | prompted | Skill description. Supplying it skips the prompt. |
+
+## `cua trajectory`
+
+Every `cua do` command is recorded into a trajectory session under
+`~/.cua/trajectories/<machine>/<YYYYMMDD-HHMMSS>/` unless `--no-record` was
+passed. Aliased as `cua traj`.
+
+| Command | Description |
+|---------|-------------|
+| `cua trajectory ls [machine]` | List sessions, optionally for one machine. Accepts `--json`. |
+| `cua trajectory view [target]` | Zip the session, serve it locally, and open it in the hosted trajectory viewer. Defaults to the newest session. |
+| `cua trajectory stop` | Stop the local file server started by `view`. |
+| `cua trajectory clean` | Delete sessions. |
+
+```console
+$ cua trajectory ls
+Machine Session Turns Created
+----------------------------------------------------------------------
+my-container 20260812-224500 1 2026-08-12T22:45:00
+```
+
+`view` accepts a machine name, a session timestamp, or a path, and takes
+`--port`/`-p` to move the local file server off its default port `8089`. It
+starts a background HTTP server on `127.0.0.1` and prints a
+`https://cua.ai/trajectory-viewer?zip=...` URL that points back at it, so the
+viewer only works while that server is running. Stop it with
+`cua trajectory stop`.
+
+`clean` takes `--older-than DAYS`, `--machine NAME`, and `-y`/`--yes` to skip
+the confirmation prompt.
+
+## `cua serve-mcp`
+
+Start a Model Context Protocol server over stdio so an AI assistant can drive
+Cua directly.
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `--permissions` | `CUA_MCP_PERMISSIONS`, else all | Comma-separated permission list. |
+| `--sandbox` | `CUA_SANDBOX` | Default sandbox for computer tools. |
+
+See [MCP server](/reference/cua-cli/mcp-server) for the permission grammar and
+the full tool catalogue.
+
+## `cua wif-token`
+
+Request a workload identity federation token for Fleets from a CI provider.
+`cua wif-token github` requests a GitHub Actions OIDC token with the `fleets`
+audience and prints only the raw token; it does not use the interactive session.
+
+It only runs inside GitHub Actions:
+
+```console
+$ cua wif-token github
+Error: ACTIONS_ID_TOKEN_REQUEST_URL is missing; run in GitHub Actions with permissions: id-token: write.
+```
+
+See [Authentication](/reference/cua-cli/authentication#github-actions) for the
+workflow snippet.
+
+## Files the CLI writes
+
+| Path | Written by |
+|------|------------|
+| OS credential vault, service `run.cua.ai`, account `cua-cli` | `cua auth login` |
+| `~/.cua/do_target.json` | `cua do switch`, `cua do zoom` |
+| `~/.cua/host_consented` | `cua do-host-consent` |
+| `~/.cua/skills/` | `cua skills record` |
+| `~/.cua/trajectories/` | `cua do` |
+| `~/.cua/sandboxes/` | local sandbox state, written when a local launch completes |
+| `~/.cua/cua-sandbox/` | disk images and overlays for local sandboxes |
+| `~/.local/share/cua/images/` | `cua image create`, `cua image pull` |
+| `~/.local/state/cua/images.json` | the local image registry |
+
+Local sandboxes and local images are stored in two separate trees, which is
+worth knowing when you are reclaiming disk space. `cua sb launch --local` works
+under `~/.cua/cua-sandbox/`:
+
+| Path | Contents |
+|------|----------|
+| `images/container-disks/<digest>/disk.qcow2` | pulled container disks, content-addressed, reused across launches |
+| `images/<name>-<hash>/disk.qcow2` | built base images |
+| `images/sessions/<sandbox>.qcow2` | per-sandbox overlay for a running sandbox, plus `<sandbox>.efivars.fd` for EFI guests |
+| `image-cache/` | downloaded image files, keyed by hash and original filename |
+
+`cua image create` and `cua image pull` write to `~/.local/share/cua/images/`
+instead. That path and `~/.local/state/cua/` follow the XDG base directory spec
+and move with `XDG_DATA_HOME` and `XDG_STATE_HOME`; `~/.cua/` does not.
diff --git a/docs/content/docs/reference/cua-cli/mcp-server.mdx b/docs/content/docs/reference/cua-cli/mcp-server.mdx
new file mode 100644
index 0000000000..590b35fa0e
--- /dev/null
+++ b/docs/content/docs/reference/cua-cli/mcp-server.mdx
@@ -0,0 +1,137 @@
+---
+title: MCP server
+description: The cua serve-mcp stdio server, its permission grammar, and the tools each permission exposes.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+`cua serve-mcp` starts a Model Context Protocol server on stdio that exposes
+sandbox management, computer control, and skills to an MCP client. It requires
+the `mcp` extra:
+
+```bash
+pip install --extra-index-url https://wheels.cua.ai/simple "cua-cli[mcp]"
+```
+
+Without it the command exits 1 with
+`MCP support not installed. Run: pip install cua-cli[mcp]`.
+
+## Running it
+
+The server speaks MCP over stdin/stdout and logs to stderr, so it is started by
+the client rather than by you. Register it with Claude Code:
+
+```bash
+claude mcp add cua -- cua serve-mcp
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--permissions` | `CUA_MCP_PERMISSIONS`, else every permission | Comma-separated permissions. |
+| `--sandbox` | `CUA_SANDBOX` | Default sandbox name for the computer tools. |
+
+```bash
+claude mcp add cua -- cua serve-mcp --permissions sandbox:readonly,computer:readonly --sandbox my-sandbox
+```
+
+The server reports its enabled permissions on startup, which is the quickest way
+to confirm a grant landed as intended:
+
+```
+2026-08-12 22:20:50,897 - cua-mcp - INFO - Enabled permissions: ['sandbox:list', 'sandbox:get']
+2026-08-12 22:20:50,909 - cua-mcp - INFO - Starting CUA MCP server...
+```
+
+## Permissions
+
+A permission is either a single `group:action` string or one of the shorthand
+groups below. Only tools covered by the granted permissions are registered, so
+an ungranted tool is not merely refused at call time — the client never sees it.
+
+| Group | Expands to |
+|-------|-----------|
+| `all` | Every permission. |
+| `sandbox:all` | `sandbox:list`, `create`, `delete`, `start`, `stop`, `restart`, `suspend`, `get`, `vnc` |
+| `sandbox:readonly` | `sandbox:list`, `sandbox:get` |
+| `computer:all` | `computer:screenshot`, `click`, `type`, `key`, `scroll`, `drag`, `hotkey`, `clipboard`, `file`, `shell`, `window` |
+| `computer:readonly` | `computer:screenshot` |
+| `skills:all` | `skills:list`, `read`, `record`, `delete` |
+| `skills:readonly` | `skills:list`, `skills:read` |
+
+<Callout type="warn">
+ **An empty or unrecognized permission list grants everything.** With no
+ `--permissions` and no `CUA_MCP_PERMISSIONS`, the server logs
+ `No permissions specified, granting all permissions` and registers all 47
+ tools. A misspelled permission is skipped with a `WARNING: Unknown permission`
+ line — and if it was the only one you passed, the resulting empty set is
+ treated as "unspecified" and again grants everything. Read the
+ `Enabled permissions:` line on startup rather than assuming the flag was
+ understood.
+</Callout>
+
+## Tools
+
+The permission that registers each tool:
+
+### Sandbox
+
+| Permission | Tools |
+|------------|-------|
+| `sandbox:list` | `sandbox_list` |
+| `sandbox:get` | `sandbox_get` |
+| `sandbox:create` | `sandbox_create` |
+| `sandbox:delete` | `sandbox_delete` |
+| `sandbox:start` | `sandbox_start` |
+| `sandbox:stop` | `sandbox_stop` |
+| `sandbox:restart` | `sandbox_restart` |
+| `sandbox:suspend` | `sandbox_suspend` |
+| `sandbox:vnc` | `sandbox_vnc` |
+
+### Computer
+
+| Permission | Tools |
+|------------|-------|
+| `computer:screenshot` | `computer_screenshot`, `computer_get_screen_size`, `computer_get_cursor_position`, `computer_get_accessibility_tree`, `computer_get_current_window` |
+| `computer:click` | `computer_click`, `computer_double_click`, `computer_move_cursor`, `computer_mouse_down`, `computer_mouse_up` |
+| `computer:type` | `computer_type` |
+| `computer:key` | `computer_key`, `computer_key_down`, `computer_key_up` |
+| `computer:hotkey` | `computer_hotkey` |
+| `computer:scroll` | `computer_scroll` |
+| `computer:drag` | `computer_drag` |
+| `computer:clipboard` | `computer_clipboard_get`, `computer_clipboard_set` |
+| `computer:file` | `computer_file_read`, `computer_file_write`, `computer_file_list` |
+| `computer:shell` | `computer_shell` |
+| `computer:window` | `computer_window_list`, `computer_window_open`, `computer_window_focus`, `computer_window_unfocus`, `computer_window_minimize`, `computer_window_maximize`, `computer_window_close`, `computer_window_resize`, `computer_window_move`, `computer_window_get_info`, `computer_launch` |
+
+### Skills
+
+| Permission | Tools |
+|------------|-------|
+| `skills:list` | `skills_list` |
+| `skills:read` | `skills_read` |
+| `skills:record` | `skills_record` |
+| `skills:delete` | `skills_delete` |
+
+<Callout type="info">
+ `computer:readonly` is not screenshot-only in practice: `computer:screenshot`
+ also registers screen size, cursor position, the accessibility tree, and the
+ current window. It reads the screen and never acts on it, but it reads more
+ than a picture.
+</Callout>
+
+## Choosing a grant
+
+`computer:shell` and `computer:file` give the client arbitrary command execution
+and filesystem access inside the target machine, and `sandbox:delete` destroys
+machines. Grant the narrowest set that lets the assistant do its job:
+
+| Intent | Grant |
+|--------|-------|
+| Let an assistant look, not touch | `sandbox:readonly,computer:readonly` |
+| Drive a UI without a shell | `computer:screenshot,computer:click,computer:type,computer:key,computer:scroll` |
+| Full automation of one sandbox | `computer:all` plus `--sandbox <name>` |
+| Everything | `all` |
+
+Authentication comes from the same session as the rest of the CLI, so
+`cua auth status` must report a session before the sandbox tools can reach the
+cloud. See [Authentication](/reference/cua-cli/authentication).
diff --git a/docs/content/docs/reference/cua-cli/meta.json b/docs/content/docs/reference/cua-cli/meta.json
new file mode 100644
index 0000000000..b2e91d9dd1
--- /dev/null
+++ b/docs/content/docs/reference/cua-cli/meta.json
@@ -0,0 +1 @@
+{ "title": "Cua CLI", "pages": ["cli-reference", "authentication", "mcp-server"] }
diff --git a/docs/content/docs/reference/index.mdx b/docs/content/docs/reference/index.mdx
index 36cc1ec2c3..cbc3c3b198 100644
--- a/docs/content/docs/reference/index.mdx
+++ b/docs/content/docs/reference/index.mdx
@@ -1,12 +1,13 @@
---
title: 'Reference'
-description: 'Index of reference material for Cua Driver, Lume, the Sandbox SDK, and Cua-Bench.'
+description: 'Index of reference material for the Cua CLI, Cua Driver, Lume, the Sandbox SDK, and Cua-Bench.'
---
-Reference documents the full technical specification for Cua's subsystems. It covers `cua-driver`, Lume, the Sandbox SDK, Cua-Bench, and the Docs & Code MCP server. The pages define commands, APIs, exposed tools, types, and stated limits.
+Reference documents the full technical specification for Cua's subsystems. It covers the `cua` CLI, `cua-driver`, Lume, the Sandbox SDK, Cua-Bench, and the Docs & Code MCP server. The pages define commands, APIs, exposed tools, types, and stated limits.
| Section | What it documents |
|---------|-------------------|
+| [Cua CLI](/reference/cua-cli/cli-reference) | Commands for the `cua` CLI, how it authenticates and stores credentials, and the MCP server it serves to AI assistants. |
| [`cua-driver`](/reference/cua-driver/cli-reference) | CLI commands, the generated MCP tool reference for the stdio MCP server, and known behavioral limits for best-effort background automation. |
| [Lume](/reference/lume/cli-reference) | CLI commands, local HTTP API, and host limits for creating, running, and managing macOS and Linux VMs on Apple Silicon Macs. |
| [Sandbox SDK](/reference/sandbox-sdk) | Python API reference for building images, creating sandboxes, and driving their interfaces. |
diff --git a/docs/content/docs/reference/meta.json b/docs/content/docs/reference/meta.json
index cab3d5a508..1af55c4e42 100644
--- a/docs/content/docs/reference/meta.json
+++ b/docs/content/docs/reference/meta.json
@@ -3,6 +3,7 @@
"icon": "BookText",
"pages": [
"index",
+ "cua-cli",
"cua-driver",
"lume",
"sandbox-sdk",