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.8.3. 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 directly from the shell.

Sends the tool request to the required Cua Driver daemon. JSON arguments may be passed as a positional JSON object or through stdin. If the daemon is unavailable, the command fails; it never executes the tool in the CLI process.

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.

Every MCP process is a stdio proxy to a Cua Driver daemon. On macOS it can auto-launch the CuaDriver.app daemon so TCC grants attach to the bundle. On Windows and Linux, the daemon must already be running.

Options:

Name	Type	Default	Description
`--socket`	String	—	Override the required daemon socket or named-pipe path.
`--host-bundle-id`	String	—	Advisory host bundle id label echoed in check_permissions output (embedded mode).

Flags:

Name	Description
`--claude-code-computer-use-compat`	Expose the Claude Code computer-use compatibility screenshot surface.
`--embedded`	Require a daemon spawned by the embedding host 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.
`--host-bundle-id`	String	—	Advisory host bundle id label echoed in check_permissions output (embedded mode).

Flags:

Name	Description
`--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.

`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 daemon and is shared across daemon-backed clients.

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 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.

`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 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 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 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 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 dump-docs`#