Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.jsonnew file mode 100644index 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.mdxindex 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.jsonindex 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",