cua do
One-shot computer actions (screenshot, click, type, windows) against a selected target.
One-shot computer actions (screenshot, click, type, windows) against a selected target.
| Command | Description |
|---|---|
cua do | One-shot computer actions against the selected target. |
cua do switch | Select the target: a sandbox name, host, url <URL>, or a legacy <provider> <name> pair. |
cua do status | Show the current target and zoom state. |
cua do ls | List targets (optionally of one provider). |
cua do zoom | Crop screenshots to a window and map coordinates into it. |
cua do unzoom | Return to full-screen screenshots. |
cua do screenshot | Take a screenshot (saved to ~/.cua/screenshots, newest 20 kept, unless --save). |
cua do snapshot | Screenshot plus an AI summary of the screen and its interactive elements (needs ANTHROPIC_API_KEY). |
cua do click | Click at image coordinates. |
cua do dclick | Double-click at image coordinates. |
cua do move | Move the cursor (image coordinates). |
cua do type | Type text. |
cua do key | Press a key (enter, escape, tab, ...). |
cua do hotkey | Keyboard shortcut (cmd+c, ctrl+shift+s). |
cua do scroll | Scroll in a direction. |
cua do drag | Drag between two points (image coordinates). |
cua do shell | Run a shell command, or open an interactive terminal (PTY) when no command is given on a terminal. |
cua do open | Open a file or URL. |
cua do launch | Launch an application. |
cua do window | Window management. |
cua do window ls | List windows (optionally filtered by app or title). |
cua do window unfocus | Remove focus from the current window (presses Escape). |
cua do window focus | Focus a window. |
cua do window minimize | Minimize a window. |
cua do window maximize | Maximize a window. |
cua do window restore | Restore a minimized or maximized window. |
cua do window close | Close a window. |
cua do window resize | Resize a window. |
cua do window move | Move a window. |
cua do window info | Show a window as JSON. |
cua do a11y | Accessibility tree and actions. |
cua do a11y tree | Print the accessibility tree (JSON). |
cua do a11y find | Find elements by name (and role). |
cua do a11y act | Act on an element: press, focus, set-value, increment, ... |
cua do cursor | Print the cursor position (screen points). |
cua do clipboard | Clipboard text. |
cua do clipboard get | Print clipboard text. |
cua do clipboard set | Set clipboard text. |
cua do-host-consent | Grant consent for cua do switch host. |
Every command also accepts the global options.
cua do#One-shot computer actions against the selected target.
cua do [OPTIONS] <COMMAND>| Flag | Type | Default | Description |
|---|---|---|---|
--no-record | boolean | false | Disable trajectory recording for this command. |
Examples
# Act on a sandbox, then take a screenshot
cua do switch dev
cua do screenshotcua do switch#Select the target: a sandbox name, host, url <URL>, or a legacy <provider> <name> pair.
cua do switch [OPTIONS] <TARGET> [NAME]| Argument | Type | Default | Description |
|---|---|---|---|
<TARGET> | string | required | Sandbox name or ref, host, url, or a legacy provider word. |
<NAME> | string | optional | The URL after url, or the sandbox name after a provider word. |
| Flag | Type | Default | Env var | Description |
|---|---|---|---|---|
--token | string | CUA_ENV_TOKEN | spacesd token (url and host). | |
--as | string | Sandbox name to register a url target under. |
Examples
cua do switch dev
cua do switch cloud:dev
# This machine (after `cua do-host-consent`)
cua do switch hostcua do status#Show the current target and zoom state.
cua do status [OPTIONS]Examples
cua do statuscua do ls#List targets (optionally of one provider).
cua do ls [OPTIONS] [PROVIDER]| Argument | Type | Default | Description |
|---|---|---|---|
<PROVIDER> | string | optional | Only targets of this provider. |
Examples
cua do lscua do zoom#Crop screenshots to a window and map coordinates into it.
cua do zoom [OPTIONS] <WINDOW_NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_NAME> | string | required | Window title or app name. |
Examples
cua do zoom Firefoxcua do unzoom#Return to full-screen screenshots.
cua do unzoom [OPTIONS]Examples
cua do unzoomcua do screenshot#Take a screenshot (saved to ~/.cua/screenshots, newest 20 kept, unless --save).
cua do screenshot [OPTIONS]| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--save | -s | path | Save the PNG here. |
Examples
cua do screenshot
cua do screenshot --save desktop.pngcua do snapshot#Screenshot plus an AI summary of the screen and its interactive elements (needs ANTHROPIC_API_KEY).
cua do snapshot [OPTIONS] [INSTRUCTIONS]...| Argument | Type | Default | Description |
|---|---|---|---|
<INSTRUCTIONS>... | string | optional | What to focus the summary on. Repeatable. |
| Flag | Type | Default | Description |
|---|---|---|---|
--model | string | Model (default claude-haiku-4-5, or CUA_SNAPSHOT_MODEL). |
Examples
cua do snapshot
cua do snapshot find the search boxcua do click#Click at image coordinates.
cua do click [OPTIONS] <X> <Y> [BUTTON]| Argument | Type | Default | Description |
|---|---|---|---|
<X> | integer | required | X in screenshot pixels. |
<Y> | integer | required | Y in screenshot pixels. |
<BUTTON> | left | right | middle | left | Mouse button. |
Examples
cua do click 640 360
cua do click 640 360 rightcua do dclick#Double-click at image coordinates.
cua do dclick [OPTIONS] <X> <Y>| Argument | Type | Default | Description |
|---|---|---|---|
<X> | integer | required | X in screenshot pixels. |
<Y> | integer | required | Y in screenshot pixels. |
Examples
cua do dclick 640 360cua do move#Move the cursor (image coordinates).
cua do move [OPTIONS] <X> <Y>| Argument | Type | Default | Description |
|---|---|---|---|
<X> | integer | required | X in screenshot pixels. |
<Y> | integer | required | Y in screenshot pixels. |
Examples
cua do move 640 360cua do type#Type text.
cua do type [OPTIONS] <TEXT>| Argument | Type | Default | Description |
|---|---|---|---|
<TEXT> | string | required | Text to type. |
Examples
cua do type 'hello world'cua do key#Press a key (enter, escape, tab, ...).
cua do key [OPTIONS] <KEY>| Argument | Type | Default | Description |
|---|---|---|---|
<KEY> | string | required | Key name. |
Examples
cua do key entercua do hotkey#Keyboard shortcut (cmd+c, ctrl+shift+s).
cua do hotkey [OPTIONS] <KEYS>| Argument | Type | Default | Description |
|---|---|---|---|
<KEYS> | string | required | Keys joined with +. |
Examples
cua do hotkey ctrl+shift+scua do scroll#Scroll in a direction.
cua do scroll [OPTIONS] <DIRECTION> [AMOUNT]| Argument | Type | Default | Description |
|---|---|---|---|
<DIRECTION> | up | down | left | right | required | Direction. |
<AMOUNT> | integer | 3 | Scroll steps. |
Examples
cua do scroll down
cua do scroll up 10cua do drag#Drag between two points (image coordinates).
cua do drag [OPTIONS] <X1> <Y1> <X2> <Y2>| Argument | Type | Default | Description |
|---|---|---|---|
<X1> | integer | required | Start X in screenshot pixels. |
<Y1> | integer | required | Start Y in screenshot pixels. |
<X2> | integer | required | End X in screenshot pixels. |
<Y2> | integer | required | End Y in screenshot pixels. |
Examples
cua do drag 100 200 400 200cua do shell#Run a shell command, or open an interactive terminal (PTY) when no command is given on a terminal.
cua do shell [OPTIONS] [COMMAND]...| Argument | Type | Default | Description |
|---|---|---|---|
<COMMAND>... | string | optional | Command and arguments. Repeatable. |
| Flag | Type | Default | Description |
|---|---|---|---|
--cols | integer | Terminal width (default: this terminal's). | |
--rows | integer | Terminal height (default: this terminal's). |
Examples
cua do shell ls -la /tmp
# An interactive terminal
cua do shellcua do open#Open a file or URL.
cua do open [OPTIONS] <PATH>| Argument | Type | Default | Description |
|---|---|---|---|
<PATH> | string | required | File path or URL in the target. |
Examples
cua do open https://example.comcua do launch#Launch an application.
cua do launch [OPTIONS] <APP> [ARGS]...| Argument | Type | Default | Description |
|---|---|---|---|
<APP> | string | required | Application name or path. |
<ARGS>... | string | optional | Arguments passed to the application. Repeatable. |
Examples
cua do launch firefox
cua do launch firefox --private-windowcua do window#Window management.
cua do window [OPTIONS] <COMMAND>cua do window ls#List windows (optionally filtered by app or title).
cua do window ls [OPTIONS] [APP]| Argument | Type | Default | Description |
|---|---|---|---|
<APP> | string | optional | Only windows whose app or title contains this. |
Examples
cua do window ls
cua do window ls firefoxcua do window unfocus#Remove focus from the current window (presses Escape).
cua do window unfocus [OPTIONS]Examples
cua do window unfocuscua do window focus#Focus a window.
cua do window focus [OPTIONS] <WINDOW_ID>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_ID> | string | required | Window id (from cua do window ls). |
Examples
cua do window focus <window-id>cua do window minimize#Minimize a window.
cua do window minimize [OPTIONS] <WINDOW_ID>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_ID> | string | required | Window id (from cua do window ls). |
Examples
cua do window minimize <window-id>cua do window maximize#Maximize a window.
cua do window maximize [OPTIONS] <WINDOW_ID>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_ID> | string | required | Window id (from cua do window ls). |
Examples
cua do window maximize <window-id>cua do window restore#Restore a minimized or maximized window.
cua do window restore [OPTIONS] <WINDOW_ID>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_ID> | string | required | Window id (from cua do window ls). |
Examples
cua do window restore <window-id>cua do window close#Close a window.
cua do window close [OPTIONS] <WINDOW_ID>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_ID> | string | required | Window id (from cua do window ls). |
Examples
cua do window close <window-id>cua do window resize#Resize a window.
cua do window resize [OPTIONS] <WINDOW_ID> <WIDTH> <HEIGHT>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_ID> | string | required | Window id (from cua do window ls). |
<WIDTH> | integer | required | Width in screen points. |
<HEIGHT> | integer | required | Height in screen points. |
Examples
cua do window resize <window-id> 1280 800cua do window move#Move a window.
cua do window move [OPTIONS] <WINDOW_ID> <X> <Y>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_ID> | string | required | Window id (from cua do window ls). |
<X> | integer | required | Left edge in screen points. |
<Y> | integer | required | Top edge in screen points. |
Examples
cua do window move <window-id> 0 0cua do window info#Show a window as JSON.
cua do window info [OPTIONS] <WINDOW_ID>| Argument | Type | Default | Description |
|---|---|---|---|
<WINDOW_ID> | string | required | Window id (from cua do window ls). |
Examples
cua do window info <window-id>cua do a11y#Accessibility tree and actions.
cua do a11y [OPTIONS] <COMMAND>cua do a11y tree#Print the accessibility tree (JSON).
cua do a11y tree [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--window | string | Only this window (default: the focused one). | |
--depth | integer | 0 | Maximum depth (0: unlimited). |
Examples
cua do a11y tree
cua do a11y tree --window <window-id> --depth 4cua do a11y find#Find elements by name (and role).
cua do a11y find [OPTIONS] <NAME>| Argument | Type | Default | Description |
|---|---|---|---|
<NAME> | string | required | Element name (substring). |
| Flag | Type | Default | Description |
|---|---|---|---|
--role | string | Only elements with this role. | |
--window | string | Only this window (default: the focused one). |
Examples
cua do a11y find Save --role buttoncua do a11y act#Act on an element: press, focus, set-value, increment, ...
cua do a11y act [OPTIONS] <ELEMENT> [ACTION] [VALUE]| Argument | Type | Default | Description |
|---|---|---|---|
<ELEMENT> | string | required | Element id from tree or find. |
<ACTION> | string | press | Action. |
<VALUE> | string | optional | Value for set-value. |
| Flag | Type | Default | Description |
|---|---|---|---|
--snapshot | string | Snapshot id from tree/find (default: the latest). |
Examples
cua do a11y act <element-id>
cua do a11y act <element-id> set-value 'hello'cua do cursor#Print the cursor position (screen points).
cua do cursor [OPTIONS]Examples
cua do cursorcua do clipboard#Clipboard text.
cua do clipboard [OPTIONS] <COMMAND>cua do clipboard get#Print clipboard text.
cua do clipboard get [OPTIONS]Examples
cua do clipboard getcua do clipboard set#Set clipboard text.
cua do clipboard set [OPTIONS] <TEXT>| Argument | Type | Default | Description |
|---|---|---|---|
<TEXT> | string | required | Text to put on the clipboard. |
Examples
cua do clipboard set 'hello'cua do-host-consent#Grant consent for cua do switch host.
cua do-host-consent [OPTIONS]Examples
# Allow `cua do` to act on this machine's desktop
cua do-host-consent| 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. |