cua doctor
Check the host, an image and a sandbox guest, or eval parity between image variants.
Check the host, an image and a sandbox guest, or eval parity between image variants.
Every command also accepts the global options.
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>, cloud:<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 cloud:dev --strict --junit doctor.xmlcua 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| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure, or cua do reported an error. |
2 | Invalid argument, or an ambiguous sandbox name (qualify it: local:NAME, cloud:NAME). |
3 | Not found: sandbox, window, skill or image (or an image not published yet). |
4 | Not supported, or not configured (for example no Fleet credentials). |
5 | No cua-spacesd answered, or a transport failure. |
6 | Unauthenticated or permission denied (by Cua, Fleet 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. |