cua

cua [command] [options]

cua is the command-line interface for Cua, an open-source computer-use platform. It authenticates against Cua cloud, launches and drives sandboxes (Linux, Windows, macOS, or Android), manages images, records skills and trajectories, and serves an MCP endpoint for AI assistants.Local launches (`--local`) use Docker, QEMU/KVM, or Lume on the current host and do not need a cloud account. Cloud work uses two different backends: `--pool` claims a sandbox from a Cua Fleet pool at `https://run.cua.ai` (the supported path), while launching a cloud image without `--pool` still talks to the older VM API whose host has been retired.The CLI is the `cua-cli` Python package. Command groups have short aliases (`sb` for `sandbox`, `img` for `image`, `traj` for `trajectory`). Bare `cua` prints help and exits 0.

auth

Manage the Cua cloud session (`login`, `logout`, `status`). Tokens are stored in the OS credential vault, not in a file the CLI writes itself.

Create and control sandboxes, cloud or local (`launch`, `ls`, `info`, `exec`, `shell`, `suspend`, `resume`, `restart`, `vnc`, `delete`).

Manage sandbox images. Cloud images live in the Cua workspace; local images live under `~/.local/share/cua/images/`.

Inspect platform definitions `cua image create` can build from (`linux-docker`, `linux-qemu`, `windows-qemu`, `android-qemu`, `macos-lume`) and whether this host meets their requirements.

Send one automation command (click, type, screenshot, shell) to a selected target machine and exit. The current target is kept in `~/.cua/do_target.json`.

Record demonstrations on a sandbox and store them as skills for agents (`record`, `list`, `read`, `replay`, `delete`, `clean`). Requires the `skills` extra for recording.

List, view, or delete sessions recorded from `cua do` under `~/.cua/trajectories/`.

Start a Model Context Protocol server on stdio so an AI assistant can drive Cua.

Exchange a CI provider identity for a Fleets workload token. `cua wif-token github` runs only inside GitHub Actions.

Grant consent for `cua do switch host` (drive this machine's desktop). Writes `~/.cua/host_consented`.

Show help for the CLI or any subcommand.

Print the installed `cua-cli` version and exit.

Target a sandbox or image on this machine instead of Cua cloud. Used by `sandbox` and `image` commands.

Print structured JSON instead of a table or status line (most commands that produce data).

Skip the confirmation prompt on delete.

OS credential vault (service `run.cua.ai`, account `cua-cli`)

Refresh and access tokens from `cua auth login`. On Linux this is Secret Service (`gnome-keyring`, KWallet). Headless hosts have no vault by default.

Fleet workload token. When set, it takes precedence over the interactive session for Fleet operations.

Selects a `keyring` backend. Needed on headless Linux, for example `keyrings.cryptfile.cryptfile.CryptFileKeyring` or `keyrings.alt.file.PlaintextKeyring`.

Default permission list and sandbox for `cua serve-mcp`. Overridden by `--permissions` and `--sandbox`.

Last `cua do switch` target and zoom state.

Marker written by `cua do-host-consent`. Remove the file to revoke host-desktop consent.

Local images (`cua image create` / `pull`) and local sandbox disks (`cua sb launch --local`). The XDG paths follow `XDGDATAHOME` / `XDGSTATEHOME`; `~/.cua/` does not.

`cua auth login` does not authorize Fleet pool claims. `cua sb launch --pool` needs `FLEETSTOKEN` or a `CUACLIENTID` / `CUACLIENT_SECRET` pair; a valid `cua auth status` is not enough.Cloud image launches without `--pool` go through the retired `api.cua.ai` VM API and fail. Use `--pool` for cloud sandboxes or `--local` for this machine. Fleet has no list operation: `cua sb ls` cannot list cloud sandboxes; address them by name with `cua sb info`.On Linux without a keyring, `cua auth login` fails after the browser approval because there is nowhere to store the refresh token. Install an encrypted or (on throwaway hosts only) plaintext file backend first.`CUAAPIKEY` is not a CLI login path. Setting it routes SDK calls away from Fleet onto the retired VM API.`cua do switch host` plus `cua do-host-consent` grants keyboard, mouse, and screen access to this desktop until `~/.cua/host_consented` is removed.

Cua is developed by Cua AI, Inc. The cua CLI (`cua-cli`) was introduced in April 2026 to manage cloud and local sandboxes from the terminal. It is a Python package published on Cua's own wheel index (`https://wheels.cua.ai/simple`), not on the default PyPI simple index.

docker(1), qemu(1), lima(1), ssh(1), uv(1), pip(1)

Source code · Homepage · Documentation