CLI Reference

Command-line interface specification for Cua Driver

Cross-platform computer-use automation driver. Install via the official script:

curl -fsSL https://cua.ai/driver/install.sh | bash

Documented against Cua Driver 0.17.0. Run cua-driver --version for your installed version.

The macOS-only cua-driver permissions command is documented separately in macOS permissions.

Tool dispatch#

`cua-driver list-tools`#

List every registered MCP tool with a one-line description.

`cua-driver describe`#

Print a tool's full description and JSON input schema.

Arguments:

Name	Type	Required	Description
`<tool-name>`	String	Yes	Name of the MCP tool to describe.

`cua-driver call`#

Invoke an MCP tool through the running daemon.

Requires a Cua Driver daemon. JSON arguments may be passed as a positional JSON object or through stdin.

Arguments:

Name	Type	Required	Description
`<tool-name>`	String	Yes	Name of the MCP tool to invoke.
`<json-args>`	String	No	JSON object for the tool input schema. If omitted, stdin is read when piped.

Options:

Name	Type	Default	Description
`--screenshot-out-file`	String	—	Write the first image content block from the response to this path.
`--socket`	String	—	Override the daemon socket or named-pipe path.

Daemon management#

`cua-driver mcp`#

Run the stdio MCP server.

On Windows and Linux, bare cua-driver mcp owns its runtime directly and shuts it down on stdin EOF. On macOS it proxies to CuaDriver.app so desktop permissions retain the app identity. Pass --direct to make the macOS MCP process own the runtime and TCC attribution, or --socket to select an explicit daemon endpoint.

Options:

Name	Type	Default	Description
`--socket`	String	—	Select an explicit daemon socket or named-pipe endpoint.
`--host-bundle-id`	String	—	Advisory host bundle id label echoed in check_permissions output (embedded mode).
`--cursor-theme`	String	cua.default	Select an installed cursor theme id.
`--cursor-reduced-motion`	String	auto	Follow the OS setting, force still frames, or allow animation: auto, on, or off.
`--grant`	String	—	Pre-authorize a residual standard-mode boundary for a newly launched runtime. Repeatable; supported value: existing-profile.

Flags:

Name	Description
`--direct`	Own the runtime in this MCP process; mutually exclusive with --socket.
`--claude-code-computer-use-compat`	Accepted for older Claude Code setup snippets; no standalone screenshot tool — use get_window_state for window screenshots.
`--embedded`	Declare embedding-host mode. Without --direct, require the host's private service through --socket instead of auto-launching the standalone app.

`cua-driver serve`#

Run Cua Driver as a long-running daemon.

The daemon owns per-process state such as element-index caches, recording state, and cursor overlay state.

Options:

Name	Type	Default	Description
`--socket`	String	—	Override the daemon socket or named-pipe path.
`--pid-file`	String	—	Override the pid-file path on Unix targets.
`--permission-mode`	String	standard	Immutable agent authorization mode: standard, bounded, or unrestricted.
`--grant`	String	—	Pre-authorize a residual standard-mode boundary. Repeatable; supported value: existing-profile.
`--session-policy`	String	—	Immutable tool manifest required in bounded mode.
`--host-bundle-id`	String	—	Advisory host bundle id label echoed in check_permissions output (embedded mode).

Flags:

Name	Description
`--dangerously-bypass-approvals`	Select unrestricted mode and acknowledge its risk.
`--allow-legacy-existing-profile-approval`	Temporary migration flag for the unprotected file-backed existing-profile artifact.
`--approve-session-policy`	Trusted-launcher confirmation that the exact bounded manifest was reviewed.
`--no-permissions-gate`	Skip the macOS first-launch permissions gate.
`--embedded`	Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1.
`--no-overlay`	Disable the agent cursor overlay for this daemon.

`cua-driver stop`#

Ask the running daemon to exit gracefully.

Options:

Name	Type	Default	Description
`--socket`	String	—	Override the daemon socket or named-pipe path.

`cua-driver status`#

Report whether a Cua Driver daemon is running.

Options:

Name	Type	Default	Description
`--socket`	String	—	Override the daemon socket or named-pipe path.
`--pid-file`	String	—	Override the pid-file path on Unix targets.

`cua-driver mcp-config`#

Print MCP server config or a client-specific install command.

Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, qwen, droid, and zcode.

Options:

Name	Type	Default	Description
`--client`	String	—	Client name to print configuration for.

Trajectory recording#

`cua-driver recording`#

Control trajectory recording on a running daemon.

Recording state lives in the required daemon and survives client reconnects.

Options:

Name	Type	Default	Description
`--socket`	String	—	Override the daemon socket or named-pipe path.

`cua-driver recording start`#

Start trajectory recording to a directory.

Arguments:

Name	Type	Required	Description
`<output-dir>`	String	Yes	Directory to write turn folders into.

`cua-driver recording stop`#

Stop trajectory recording.

`cua-driver recording status`#

Print the current recording state.

`cua-driver recording render`#

Render a recorded trajectory directory to an MP4.

This pure file-to-file path does not require a running daemon.

Arguments:

Name	Type	Required	Description
`<input-dir>`	String	Yes	Trajectory directory containing recorded turn folders.
`<out-mp4>`	String	Yes	Output MP4 path.

Options:

Name	Type	Default	Description
`--scale`	Number	—	Scale factor for rendered frames.

Flags:

Name	Description
`--no-zoom`	Disable cursor/action zoom effects in the rendered video.

Configuration#

`cua-driver config`#

Read or mutate persistent driver configuration.

Without a subcommand, prints the full config.

Options:

Name	Type	Default	Description
`--socket`	String	—	Override the daemon socket or named-pipe path.

`cua-driver config show`#

Print the full config.

`cua-driver config get`#

Print one config key.

Arguments:

Name	Type	Required	Description
`<key>`	String	Yes	Config key to read.

`cua-driver config set`#

Set one config key.

Arguments:

Name	Type	Required	Description
`<key>`	String	Yes	Config key to write.
`<value>`	String	Yes	Value to store.

`cua-driver config reset`#

Reset config to defaults.

Diagnostics#

`cua-driver check-update`#

Check whether a newer cua-driver release is available.

Read-only. Uses the same update-state payload as the check_for_update MCP tool.

Flags:

Name	Description
`--json`	Emit a machine-readable JSON payload.
`--no-cache`	Skip the 20-hour on-disk cache and force a GitHub request.

`cua-driver update`#

Check for an update and optionally apply it.

The apply path delegates to the canonical platform installer scripts.

Flags:

Name	Description
`--apply`	Download and install the latest release when one is available.
`--json`	Emit the structured update-state payload.

`cua-driver doctor`#

Run platform-aware diagnostic probes.

Exit code is non-zero when any probe is an error.

Flags:

Name	Description
`--json`	Emit the probe report as JSON.

`cua-driver diagnose`#

Print a pasteable install-layout and permission-attribution report.

Other commands#

`cua-driver revoke`#

Revoke one or all live authorization/session scopes.

Revocation is deny-only and never accepts an approval token.

Options:

Name	Type	Default	Description
`--session`	String	—	Exact session id to stop and revoke.
`--socket`	String	—	Override the daemon socket or named-pipe path.

Flags:

Name	Description
`--all`	Stop and revoke every live session.

`cua-driver telemetry`#

Inspect or change content-free product telemetry.

Telemetry is default-on. Disable retains the pseudonymous installation ID; reset-id erases the ID and event markers while preserving the preference.

`cua-driver telemetry enable`#

Persistently enable telemetry.

`cua-driver telemetry disable`#

Persistently disable every telemetry request.

Retains the local installation ID.

`cua-driver telemetry status`#

Show the effective setting and redacted identity state.

Flags:

Name	Description
`--json`	Emit JSON.

`cua-driver telemetry reset-id`#

Erase the installation ID and event markers.

The persisted enabled/disabled preference is retained.

`cua-driver telemetry inspect`#

Build a fixed event payload without sending it.

The distinct ID is replaced with a redacted placeholder.

Arguments:

Name	Type	Required	Description
`<event>`	String	Yes	Fixed telemetry event name.

Flags:

Name	Description
`--json`	Emit JSON.

`cua-driver autostart`#

Manage platform-native daemon autostart.

Windows registers a logon Scheduled Task. macOS and Linux currently print manual-recipe guidance.

`cua-driver autostart enable`#

`cua-driver autostart disable`#

Remove the autostart entry.

`cua-driver autostart status`#

Print whether autostart is registered and running.

not-registered is emitted only when Task Scheduler explicitly reports that the named task does not exist. If the task cannot be inspected, the command exits non-zero and reports permission-denied or unknown together with the original diagnostic.

`cua-driver autostart kick`#

Start the autostart entry now without re-logging.

`cua-driver skills`#

Install, update, inspect, or remove the optional agent skill pack.

The install script never touches agent skill directories automatically.

`cua-driver skills install`#

Fetch the versioned skill pack and link detected agents.

Options:

Name	Type	Default	Description
`--agent`	String	—	Restrict linking to one agent.
`--from`	String	—	Fetch from a source such as main instead of the tagged release.

Flags:

Name	Description
`--all-platforms`	Keep platform-specific skill files for every platform.

`cua-driver skills update`#

Refresh the local skill pack and links.

`cua-driver skills uninstall`#

Remove agent skill links.

Flags:

Name	Description
`--all`	Also delete the local skill-pack copy.

`cua-driver skills status`#

Report local skill-pack and per-agent link state.

`cua-driver skills path`#

Print the local skill-pack path.

`cua-driver manifest`#

Emit a stable JSON description of the CLI surface.

Consumers can use this instead of hardcoding launch arguments such as the MCP invocation.

Flags:

Name	Description
`-p`, `--pretty`	Pretty-print JSON.

`cua-driver cursor-theme`#

Validate, compile, inspect, preview, install, or remove a local cursor theme.

This is a trusted local authoring workflow. Agent-facing tools may select an installed theme id, but cannot install source or compiled theme data.

`cua-driver cursor-theme validate`#

Validate a bounded dotLottie source archive.

Arguments:

Name	Type	Required	Description
`<source>`	String	Yes	Path to the source .lottie archive.

Flags:

Name	Description
`--development`	Allow the reserved com.example development namespace.

`cua-driver cursor-theme build`#

Compile a validated dotLottie archive into a bounded .cua-theme artifact.

Arguments:

Name	Type	Required	Description
`<source>`	String	Yes	Path to the source .lottie archive.

Options:

Name	Type	Default	Description
`--output`	String	—	Output .cua-theme path.

Flags:

Name	Description
`--development`	Allow the reserved com.example development namespace.

`cua-driver cursor-theme inspect`#

Inspect metadata in a compiled .cua-theme artifact.

Arguments:

Name	Type	Required	Description
`<theme>`	String	Yes	Path to the compiled .cua-theme artifact.

Flags:

Name	Description
`--json`	Emit machine-readable JSON.

`cua-driver cursor-theme preview`#

Render a compiled theme's representative still frames to a directory.

Arguments:

Name	Type	Required	Description
`<theme>`	String	Yes	Path to the compiled .cua-theme artifact.

Options:

Name	Type	Default	Description
`--output`	String	—	Preview output directory.

`cua-driver cursor-theme install`#

Install a compiled theme into the current user's theme store.

Arguments:

Name	Type	Required	Description
`<theme>`	String	Yes	Path to the compiled .cua-theme artifact.

`cua-driver cursor-theme list`#

List the built-in and installed cursor themes.

Flags:

Name	Description
`--json`	Emit machine-readable JSON.

`cua-driver cursor-theme uninstall`#

Remove a custom theme from the current user's theme store.

The built-in cua.default theme cannot be removed.

Arguments:

Name	Type	Required	Description
`<theme-id>`	String	Yes	Installed custom theme id.

`cua-driver dump-docs`#

Output machine-readable CLI and MCP documentation JSON.

Used by the docs generator to keep reference pages in sync with the live binary.

Options:

Name	Type	Default	Description
`--type`	String	all	Which docs to emit: all, cli, or mcp.

Flags:

Name	Description
`-p`, `--pretty`	Pretty-print JSON.

Global options#

Available on all commands:

--help — Show help information.
--version — Show version number.

CLI Reference

Tool dispatch#

cua-driver list-tools#

cua-driver describe#

cua-driver call#

Daemon management#

cua-driver mcp#

cua-driver serve#

cua-driver stop#

cua-driver status#

cua-driver mcp-config#

Trajectory recording#

cua-driver recording#

cua-driver recording start#

cua-driver recording stop#

cua-driver recording status#

cua-driver recording render#

Configuration#

cua-driver config#

cua-driver config show#

cua-driver config get#

cua-driver config set#

cua-driver config reset#

Diagnostics#

cua-driver check-update#

cua-driver update#

cua-driver doctor#

cua-driver diagnose#

Other commands#

cua-driver revoke#

cua-driver telemetry#

cua-driver telemetry enable#

cua-driver telemetry disable#

cua-driver telemetry status#

cua-driver telemetry reset-id#

cua-driver telemetry inspect#

cua-driver autostart#

cua-driver autostart enable#

cua-driver autostart disable#

cua-driver autostart status#

cua-driver autostart kick#

cua-driver skills#

cua-driver skills install#

cua-driver skills update#

cua-driver skills uninstall#

cua-driver skills status#

cua-driver skills path#

cua-driver manifest#

cua-driver cursor-theme#

cua-driver cursor-theme validate#

cua-driver cursor-theme build#

cua-driver cursor-theme inspect#

cua-driver cursor-theme preview#

cua-driver cursor-theme install#

cua-driver cursor-theme list#

cua-driver cursor-theme uninstall#

cua-driver dump-docs#

Global options#

`cua-driver list-tools`#

`cua-driver describe`#

`cua-driver call`#

`cua-driver mcp`#

`cua-driver serve`#

`cua-driver stop`#

`cua-driver status`#

`cua-driver mcp-config`#

`cua-driver recording`#

`cua-driver recording start`#

`cua-driver recording stop`#

`cua-driver recording status`#

`cua-driver recording render`#

`cua-driver config`#

`cua-driver config show`#

`cua-driver config get`#

`cua-driver config set`#

`cua-driver config reset`#

`cua-driver check-update`#

`cua-driver update`#

`cua-driver doctor`#

`cua-driver diagnose`#

`cua-driver revoke`#

`cua-driver telemetry`#

`cua-driver telemetry enable`#

`cua-driver telemetry disable`#

`cua-driver telemetry status`#

`cua-driver telemetry reset-id`#

`cua-driver telemetry inspect`#

`cua-driver autostart`#

`cua-driver autostart enable`#

`cua-driver autostart disable`#

`cua-driver autostart status`#

`cua-driver autostart kick`#

`cua-driver skills`#

`cua-driver skills install`#

`cua-driver skills update`#

`cua-driver skills uninstall`#

`cua-driver skills status`#

`cua-driver skills path`#

`cua-driver manifest`#

`cua-driver cursor-theme`#

`cua-driver cursor-theme validate`#

`cua-driver cursor-theme build`#

`cua-driver cursor-theme inspect`#

`cua-driver cursor-theme preview`#

`cua-driver cursor-theme install`#

`cua-driver cursor-theme list`#

`cua-driver cursor-theme uninstall`#

`cua-driver dump-docs`#