Computer actions

One-shot computer actions (screenshot, click, type, windows) against a selected target, and their recorded trajectories.

Command	Description
`cua do`	One-shot computer actions against the selected target.
`cua do switch`	Select the target: a sandbox name or ref, a relay Space (`relay:<id>`), `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`.
`cua trajectory`	Recorded `cua do` trajectories.
`cua trajectory ls`	List sessions.
`cua trajectory view`	Zip, serve on loopback and open the hosted viewer.
`cua trajectory stop`	Stop the file server started by `view`.
`cua trajectory clean`	Delete sessions.

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 screenshot
 
# A relay Space (`cua spaces ls`)
cua do switch relay:0123abcd4567ef89

`cua do switch`#

Select the target: a sandbox name or ref, a relay Space (relay:<id>), 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, `relay:<id>`, `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 relay:0123abcd4567ef89
 
# This machine (after `cua do-host-consent`)
cua do switch host

`cua do status`#

Show the current target and zoom state.

cua do status [OPTIONS]

Examples

cua do status

`cua 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 ls

`cua 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 Firefox

`cua do unzoom`#

Return to full-screen screenshots.

cua do unzoom [OPTIONS]

Examples

cua do unzoom

`cua 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.png

`cua 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 box

`cua 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 right

`cua 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 360

`cua 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 360

`cua 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 enter

`cua 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+s

`cua 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 10

`cua 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 200

`cua 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 shell

`cua 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.com

`cua 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-window

`cua 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 firefox

`cua do window unfocus`#

Remove focus from the current window (presses Escape).

cua do window unfocus [OPTIONS]

Examples

cua do window unfocus

`cua 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 800

`cua 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 0

`cua 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 4

`cua 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 button

`cua 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 cursor

`cua 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 get

`cua 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

`cua trajectory`#

Recorded cua do trajectories.

cua trajectory [OPTIONS] <COMMAND>

Alias: cua traj.

`cua trajectory ls`#

List sessions.

cua trajectory ls [OPTIONS] [MACHINE]

Argument	Type	Default	Description
`<MACHINE>`	string	optional	Only sessions of this target (sandbox name or `host`).

Examples

cua traj ls
 
# Only the sessions recorded on the sandbox dev
cua traj ls dev

`cua trajectory view`#

Zip, serve on loopback and open the hosted viewer.

cua trajectory view [OPTIONS] [TARGET]

Argument	Type	Default	Description
`<TARGET>`	string	optional	Session id or target name (default: the latest session).

Flag	Short	Type	Default	Description
`--port`	`-p`	integer	`8089`	Loopback port of the file server.

Examples

# The latest session
cua traj view
cua traj view <session> --port 8090

`cua trajectory stop`#

Stop the file server started by view.

cua trajectory stop [OPTIONS]

Examples

cua traj stop

`cua trajectory clean`#

Delete sessions.

cua trajectory clean [OPTIONS]

Flag	Short	Type	Default	Description
`--older-than`		integer		Only sessions older than this many days.
`--machine`		string		Only sessions of this target.
`--yes`	`-y`	boolean	`false`	Do not ask for confirmation.

Examples

# Sessions older than a week, without the prompt
cua traj clean --older-than 7 --yes

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.

Computer actions

cua do#

cua do switch#

cua do status#

cua do ls#

cua do zoom#

cua do unzoom#

cua do screenshot#

cua do snapshot#

cua do click#

cua do dclick#

cua do move#

cua do type#

cua do key#

cua do hotkey#

cua do scroll#

cua do drag#

cua do shell#

cua do open#

cua do launch#

cua do window#

cua do window ls#

cua do window unfocus#

cua do window focus#

cua do window minimize#

cua do window maximize#

cua do window restore#

cua do window close#

cua do window resize#

cua do window move#

cua do window info#

cua do a11y#

cua do a11y tree#

cua do a11y find#

cua do a11y act#

cua do cursor#

cua do clipboard#

cua do clipboard get#

cua do clipboard set#

cua do-host-consent#

cua trajectory#

cua trajectory ls#

cua trajectory view#

cua trajectory stop#

cua trajectory clean#

Exit codes#

`cua do`#

`cua do switch`#

`cua do status`#

`cua do ls`#

`cua do zoom`#

`cua do unzoom`#

`cua do screenshot`#

`cua do snapshot`#

`cua do click`#

`cua do dclick`#

`cua do move`#

`cua do type`#

`cua do key`#

`cua do hotkey`#

`cua do scroll`#

`cua do drag`#

`cua do shell`#

`cua do open`#

`cua do launch`#

`cua do window`#

`cua do window ls`#

`cua do window unfocus`#

`cua do window focus`#

`cua do window minimize`#

`cua do window maximize`#

`cua do window restore`#

`cua do window close`#

`cua do window resize`#

`cua do window move`#

`cua do window info`#

`cua do a11y`#

`cua do a11y tree`#

`cua do a11y find`#

`cua do a11y act`#

`cua do cursor`#

`cua do clipboard`#

`cua do clipboard get`#

`cua do clipboard set`#

`cua do-host-consent`#

`cua trajectory`#

`cua trajectory ls`#

`cua trajectory view`#

`cua trajectory stop`#

`cua trajectory clean`#