Account and setup

Command	Description
`cua auth`	Log in to Cua and manage the signed-in session.
`cua auth login`	Log in (browser sign-in; `--remote` for a device code), then offer to set up your AI coding agents.
`cua auth logout`	Revoke and remove the local session.
`cua auth status`	Local session state (no network).
`cua auth whoami`	Who is signed in: the account, its plan and its teams.
`cua auth provider`	Keys of the contrib sandbox providers (`--on e2b`, `--on daytona`, `--on modal`).
`cua auth provider ls`	Providers, whether this build has them and where their keys come from (never the values).
`cua auth provider set`	Store a provider key, read from stdin (no echo on a terminal).
`cua auth provider rm`	Remove a provider's stored keys.
`cua config`	User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime.
`cua config list`	Every setting: its effective value and where it comes from (env, config or default).
`cua config get`	One setting's effective value.
`cua config set`	Write a setting to the config file.
`cua config unset`	Remove a setting from the config file (the environment variable or the built-in default applies again).
`cua config path`	The config file's path.
`cua daemon`	The cua daemon.
`cua daemon start`	Start the daemon (in the background unless --foreground).
`cua daemon stop`	Stop the daemon.
`cua daemon status`	Show daemon status.
`cua daemon mcp`	Stdio MCP server backed by the daemon (started if needed): the Spaces contract tools plus the sandbox/computer/skills tools (same server as `cua mcp`).
`cua doctor`	Check the host, an image and a sandbox's guest in one report (`cua doctor [REF]`), or eval parity between two variants (`cua doctor parity A B`).
`cua doctor parity`	Eval parity between two variants of one image (rootfs vs containerDisk): doctor on both, fidelity diff, task outcomes.
`cua telemetry`	Anonymous usage telemetry (status, on, off, show-last, reset-id, schema).
`cua telemetry status`	Whether telemetry is on, why, and the exact properties every event carries.
`cua telemetry on`	Turn usage telemetry on (writes [telemetry] enabled = "on" to ~/.cua/config.toml).
`cua telemetry off`	Turn usage telemetry off (same as `cua config set telemetry off`).
`cua telemetry show-last`	Print the last events this machine queued or sent, exactly as sent.
`cua telemetry reset-id`	Delete the anonymous install id and salt (new ones are created on the next event).
`cua telemetry schema`	Every event and property that may be sent, with its allowed values.

Every command also accepts the global options.

`cua auth`#

cua auth [OPTIONS] <COMMAND>

`cua auth login`#

cua auth login [OPTIONS]

Flag	Short	Type	Default	Description
`--agents`		string		Agents: `all` (installed), `none`, or ids such as `claude,codex,hermes` (`cua agents detect` lists every supported agent).
`--mcp-command`		string		Command agents launch for the MCP server (default: the `cua` on PATH, else this binary).
`--no-browser`		boolean	`false`	Do not open a browser; print the URL.
`--remote`		boolean	`false`	Sign in from another device with a code (for SSH sessions and machines without a browser).
`--no-onboarding`		boolean	`false`	Skip the agent onboarding prompt.
`--skills-only`		boolean	`false`	Only install skills. Alias: `--no-mcp`.
`--mcp-only`		boolean	`false`	Only configure the MCP server. Alias: `--no-skills`.
`--yes`	`-y`	boolean	`false`	Answer yes to every prompt.
`--force`		boolean	`false`	Replace skill folders cua did not write (the old one is backed up).

Examples

# Sign in with the browser
cua auth login
 
# Sign in over SSH with a device code
cua auth login --remote
 
# Sign in and set up Claude Code without prompts
cua auth login --agents claude -y

`cua auth logout`#

Revoke and remove the local session.

cua auth logout [OPTIONS]

Examples

cua auth logout

`cua auth status`#

Local session state (no network).

cua auth status [OPTIONS]

Examples

cua auth status
cua auth status --json

`cua auth whoami`#

Who is signed in: the account, its plan and its teams.

cua auth whoami [OPTIONS]

Examples

cua auth whoami
cua auth whoami --json

`cua auth provider`#

Keys of the contrib sandbox providers (--on e2b, --on daytona, --on modal).

cua auth provider [OPTIONS] <COMMAND>

`cua auth provider ls`#

Providers, whether this build has them and where their keys come from (never the values).

cua auth provider ls [OPTIONS]

Alias: cua auth provider list.

Examples

cua auth provider ls
cua auth provider ls --json

`cua auth provider set`#

Store a provider key, read from stdin (no echo on a terminal). An environment variable of the same name wins over the stored key.

cua auth provider set [OPTIONS] <NAME>

Argument	Type	Default	Description
`<NAME>`	string	required	Provider (`e2b`, `daytona`, `modal`).

Flag	Type	Default	Description
`--var`	string		Only this variable (for example MODAL_TOKEN_SECRET).

Examples

# Prompt for E2B_API_KEY (no echo)
cua auth provider set e2b
 
# One variable only
cua auth provider set daytona --var DAYTONA_API_KEY

`cua auth provider rm`#

Remove a provider's stored keys.

cua auth provider rm [OPTIONS] <NAME>

Alias: cua auth provider delete.

Argument	Type	Default	Description
`<NAME>`	string	required	Provider.

Examples

cua auth provider rm e2b

`cua config`#

User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime.

cua config [OPTIONS] <COMMAND>

`cua config list`#

Every setting: its effective value and where it comes from (env, config or default).

cua config list [OPTIONS]

Alias: cua config ls.

Examples

cua config list
cua config list --json

`cua config get`#

One setting's effective value.

cua config get [OPTIONS] <KEY>

Argument	Type	Default	Description
`<KEY>`	string	required	Setting (`default.on`, `default.kind`, `default.runtime`).

Examples

cua config get default.on

`cua config set`#

Write a setting to the config file.

cua config set [OPTIONS] <KEY> <VALUE>

Argument	Type	Default	Description
`<KEY>`	string	required	Setting.
`<VALUE>`	string	required	Value (checked: `default.on` takes local, aws, gcp, modal or a provider).

Examples

# Create sandboxes in your AWS account unless --on says otherwise
cua config set default.on aws
 
# Back to this machine
cua config set default.on local
 
# Prefer VMs when the image offers both
cua config set default.kind vm

`cua config unset`#

Remove a setting from the config file (the environment variable or the built-in default applies again).

cua config unset [OPTIONS] <KEY>

Argument	Type	Default	Description
`<KEY>`	string	required	Setting.

Examples

cua config unset default.on

`cua config path`#

The config file's path.

cua config path [OPTIONS]

Examples

cua config path

`cua daemon`#

The cua daemon.

cua daemon [OPTIONS] <COMMAND>

`cua daemon start`#

Start the daemon (in the background unless --foreground).

cua daemon start [OPTIONS]

Flag	Type	Default	Description
`--socket`	path		Unix socket (default ~/.cua/cua.sock).
`--loopback`	string	`127.0.0.1:0`	Loopback address (default 127.0.0.1:0; "off" disables).
`--foreground`	boolean	`false`	Stay in the foreground.

Examples

cua daemon start
 
# In the foreground, for a service manager
cua daemon start --foreground

`cua daemon stop`#

Stop the daemon.

cua daemon stop [OPTIONS]

Examples

cua daemon stop

`cua daemon status`#

Show daemon status.

cua daemon status [OPTIONS]

Examples

cua daemon status

`cua daemon mcp`#

Stdio MCP server backed by the daemon (started if needed): the Spaces contract tools plus the sandbox/computer/skills tools (same server as cua mcp).

cua daemon mcp [OPTIONS]

Flag	Type	Default	Env var	Description
`--permissions`	string		`CUA_MCP_PERMISSIONS`	Comma-separated permissions or groups (default: all).
`--sandbox`	string		`CUA_SANDBOX`	Default sandbox for computer tools.

Examples

cua daemon mcp
cua daemon mcp --permissions spaces:all

`cua doctor`#

Check the host, an image and a sandbox's guest in one report (cua doctor [REF]), or eval parity between two variants (cua doctor parity A B).

cua doctor [OPTIONS] [TARGET]
       cua doctor <COMMAND>

Argument	Type	Default	Description
`<TARGET>`	string	optional	Sandbox to check: `local:<name>`, `direct:<host:port>`, a bare name, or a spacesd URL. Omit for the host checks only.

Flag	Type	Default	Env var	Description
`--image`	string			Image to resolve for the image checks (default: the sandbox's).
`--arch`	string			Architecture to resolve the image for (default: the sandbox's, else this host's).
`--format`	`human` \| `json` \| `junit`	`human`		Output format (`--json` selects json).
`--effects`	`none` \| `virtual`	`none`		Which guest checks may act on the guest.
`--only`	string			Guest check ids or groups to run (comma separated). Repeatable.
`--skip`	string			Guest check ids or groups to skip. Repeatable.
`--timeout`	integer	`240`		Guest budget in seconds.
`--token`	string		`CUA_ENV_TOKEN`	spacesd token for a URL target (default: CUA_ENV_TOKEN).
`--shim`	string			Check an image without cua-spacesd through its own API instead: `computer-server=<url>`, `osworld=<url>` or `mcp=<url>`.
`--expect-manifest`	path			The image's claims (manifest JSON), for the shim or to override the guest's own.
`--out`	path			Also write the JSON report here.
`--junit`	path			Also write JUnit XML here.
`--expect`	string			Fail unless the build running in the guest is the expected one: COMPONENT=WANT with WANT `sha256:<hex>` (the executable), `git:<sha>` or a version (repeatable). Components: cua-spacesd, cua-driver, or an overlay name. `cua sb create --overlay` prints the sha256 to pass.
`--strict`	boolean	`false`		Fail on warnings and on required checks that were skipped.
`--no-host`	boolean	`false`		Skip the host checks.

Examples

# Host checks only
cua doctor
 
# Host, image and guest checks for the sandbox dev
cua doctor dev
 
# CI: fail on warnings, write JUnit XML
cua doctor local:dev --strict --junit doctor.xml

`cua doctor parity`#

Eval parity between two variants of one image (rootfs vs containerDisk): doctor on both, fidelity diff, task outcomes.

cua doctor parity [OPTIONS] <A> <B>

Argument	Type	Default	Description
`<A>`	string	required	First variant (a sandbox ref or a spacesd URL).
`<B>`	string	required	Second variant.

Flag	Type	Default	Env var	Description
`--token`	string		`CUA_ENV_TOKEN`	Token for URL targets (both), default CUA_ENV_TOKEN.
`--token-b`	string			Token for B when it differs from A's.
`--tasks`	string	`builtin:form,builtin:file`		Tasks (`builtin:form`, `builtin:file`), comma separated. Repeatable.
`--allow-diff`	string			Extra fidelity keys allowed to differ. Repeatable.
`--out`	path			Write parity.json here.
`--timeout`	integer	`240`		Doctor budget per variant, seconds.

Examples

cua doctor parity local:linux-rootfs local:linux-vm
cua doctor parity local:linux-rootfs local:linux-vm --out parity.json

`cua telemetry`#

Anonymous usage telemetry (status, on, off, show-last, reset-id, schema). What is sent: https://cua.ai/docs/cua-sdk/concepts/telemetry.

cua telemetry [OPTIONS] <COMMAND>

Examples

cua telemetry status
cua telemetry off
cua telemetry show-last

`cua telemetry status`#

Whether telemetry is on, why, and the exact properties every event carries.

cua telemetry status [OPTIONS]

Examples

cua telemetry status
cua telemetry status --json

`cua telemetry on`#

Turn usage telemetry on (writes [telemetry] enabled = "on" to ~/.cua/config.toml).

cua telemetry on [OPTIONS]

Examples

cua telemetry on

`cua telemetry off`#

Turn usage telemetry off (same as cua config set telemetry off).

cua telemetry off [OPTIONS]

Examples

cua telemetry off

`cua telemetry show-last`#

Print the last events this machine queued or sent, exactly as sent.

cua telemetry show-last [OPTIONS]

Flag	Short	Type	Default	Description
`--limit`	`-n`	integer	`20`	How many.

Examples

cua telemetry show-last
cua telemetry show-last -n 5 --json

`cua telemetry reset-id`#

Delete the anonymous install id and salt (new ones are created on the next event).

cua telemetry reset-id [OPTIONS]

Examples

cua telemetry reset-id

`cua telemetry schema`#

Every event and property that may be sent, with its allowed values.

cua telemetry schema [OPTIONS]

Examples

cua telemetry schema --json

Exit codes#

Code	Meaning
`0`	Success.
`1`	Failure, or `cua do` reported an error.
`2`	Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`).
`3`	Not found: sandbox, window, skill or image (or an image not published yet).
`4`	Not supported, or not configured (for example no provider credentials).
`5`	No cua-spacesd answered, or a transport failure.
`6`	Unauthenticated or permission denied (by Cua or your cloud account).
`7`	Not enough free disk space (see `cua cache`).
`130`	Cancelled (Ctrl-C during a create): what it made was removed.

Account and setup

cua auth#

cua auth login#

cua auth logout#

cua auth status#

cua auth whoami#

cua auth provider#

cua auth provider ls#

cua auth provider set#

cua auth provider rm#

cua config#

cua config list#

cua config get#

cua config set#

cua config unset#

cua config path#

cua daemon#

cua daemon start#

cua daemon stop#

cua daemon status#

cua daemon mcp#

cua doctor#

cua doctor parity#

cua telemetry#

cua telemetry status#

cua telemetry on#

cua telemetry off#

cua telemetry show-last#

cua telemetry reset-id#

cua telemetry schema#

Exit codes#

`cua auth`#

`cua auth login`#

`cua auth logout`#

`cua auth status`#

`cua auth whoami`#

`cua auth provider`#

`cua auth provider ls`#

`cua auth provider set`#

`cua auth provider rm`#

`cua config`#

`cua config list`#

`cua config get`#

`cua config set`#

`cua config unset`#

`cua config path`#

`cua daemon`#

`cua daemon start`#

`cua daemon stop`#

`cua daemon status`#

`cua daemon mcp`#

`cua doctor`#

`cua doctor parity`#

`cua telemetry`#

`cua telemetry status`#

`cua telemetry on`#

`cua telemetry off`#

`cua telemetry show-last`#

`cua telemetry reset-id`#

`cua telemetry schema`#