CLI Reference
Command Line Interface reference for Cua Driver
macOS Accessibility-driven computer-use agent — MCP stdio server.
Tool dispatch
cua-driver call
Invoke an MCP tool directly from the shell.
Runs the same ToolHandler the MCP server uses. JSON-ARGS is a JSON object mapping to the tool's inputSchema. When JSON-ARGS is omitted and stdin is a pipe, JSON is read from stdin. When neither is provided, the tool is called with no arguments.
Examples: cua-driver call list_apps cua-driver call launch_app '{"bundle_id":"com.apple.finder"}' echo '{"pid":844,"window_id":1234}' | cua-driver call get_window_state
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
<tool-name> | String | Yes | Name of the tool to invoke (see cua-driver list-tools). |
<json-args> | String | No | JSON object string for the tool's inputSchema. If omitted, reads from stdin when stdin is a pipe. |
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--screenshot-out-file | String | — | Write the first image content block from the response to this file path. |
--socket | String | — | Override the daemon Unix socket path. |
Flags:
| Name | Description |
|---|---|
--raw | Print the raw CallTool.Result JSON (content + structuredContent + isError) instead of unwrapping structuredContent. |
--compact | Emit minified JSON instead of pretty-printed. |
--no-daemon | Skip the cua-driver daemon even if one is running. |
cua-driver list-tools
List every tool exposed by cua-driver with its one-line description.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the daemon Unix socket path. |
Flags:
| Name | Description |
|---|---|
--no-daemon | Skip the cua-driver daemon even if one is running. |
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 tool to describe. |
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the daemon Unix socket path. |
Flags:
| Name | Description |
|---|---|
--compact | Emit minified JSON instead of pretty-printed. |
--no-daemon | Skip the cua-driver daemon even if one is running. |
Daemon management
cua-driver mcp
Run the stdio MCP server.
When invoked from a shell or IDE terminal (Claude Code, Cursor,
VS Code, Warp), macOS TCC attributes the process to the parent
terminal — not to CuaDriver.app — so AX probes silently fail
against the wrong bundle id. To sidestep this without breaking
the stdio MCP transport, mcp detects the context, ensures a
cua-driver serve daemon is running under LaunchServices
(relaunching via open -n -g -a CuaDriver --args serve if not),
and proxies every MCP tool call through the daemon's Unix
socket. Tool semantics are identical to the in-process path.
Pass --no-daemon-relaunch (or set CUA_DRIVER_MCP_NO_RELAUNCH=1)
to force in-process execution — useful when the calling context
already has the right TCC grants (e.g. spawned from CuaDriver.app
directly), or for diagnosing in-process failures.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the daemon Unix socket path used by the proxy fallback. |
Flags:
| Name | Description |
|---|---|
--claude-code-computer-use-compat | Expose normal CuaDriver tools, replacing only screenshot with a Claude Code-friendly window-only screenshot that establishes the vision coordinate frame. |
--no-daemon-relaunch | Stay in the current process instead of auto-launching a daemon and proxying through its Unix socket when invoked from a shell without CuaDriver.app's TCC grants. Also toggleable via CUA_DRIVER_MCP_NO_RELAUNCH=1. |
cua-driver serve
Run cua-driver as a long-running daemon on a Unix domain socket.
Listens on --socket (default: ~/Library/Caches/cua-driver/cua-driver.sock).
Subsequent cua-driver call/list-tools/describe invocations auto-detect
the socket and forward their requests, so the AppStateEngine's per-pid
element_index cache survives across CLI calls.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the Unix socket path. |
Flags:
| Name | Description |
|---|---|
--no-relaunch | Stay in the current process instead of re-execing via open -n -g -a CuaDriver. |
cua-driver stop
Ask the running cua-driver daemon to exit gracefully.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the Unix socket path. |
cua-driver status
Report whether a cua-driver daemon is running.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the Unix socket path. |
--pid-file | String | — | Override the daemon pid-file path. |
cua-driver mcp-config
Print MCP server config or a client-specific install command.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--client | String | — | Client to print the install command for: claude | codex | cursor | openclaw | opencode | hermes | pi. Omit for the generic JSON snippet. |
Flags:
| Name | Description |
|---|---|
--claude-code-computer-use-compat | Print config for Claude Code's window-scoped screenshot compatibility mode registered as cua-computer-use. |
Trajectory recording
cua-driver recording
Control the trajectory recorder on a running cua-driver daemon.
Wraps the set_recording and get_recording_state tools
with human-friendly output. All subcommands require a
running daemon (cua-driver serve) because recording
state lives in-process and doesn't survive CLI-process
lifetimes.
cua-driver recording start
Enable trajectory recording to the given directory.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
<output-dir> | String | Yes | Directory to write turn folders into. Expands ~; created if missing. |
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the daemon Unix socket path. |
Flags:
| Name | Description |
|---|---|
--video-experimental | Also capture the main display to <output-dir>/recording.mp4 via SCStream. Experimental, off by default. |
cua-driver recording stop
Disable trajectory recording.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the daemon Unix socket path. |
cua-driver recording status
Report whether recording is currently enabled.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the daemon Unix socket path. |
cua-driver recording render
Render a captured recording directory to a zoomed MP4.
Reads <input-dir>/session.json, <input-dir>/recording.mp4,
<input-dir>/cursor.jsonl, and every <input-dir>/turn-*/action.json,
then produces a single zoom-on-click MP4 at --output.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
<input-dir> | String | Yes | Recording directory (contains session.json + recording.mp4 + cursor.jsonl + turn-*/). |
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--output | String | — | Destination path for the rendered MP4. Overwrites any existing file. |
--scale | Double | 2.0 | Zoom factor applied to each click event. 1.0 disables zoom; 2.0 is 2× magnification. |
Flags:
| Name | Description |
|---|---|
--no-zoom | Skip the zoom curve and re-encode the input as-is. Useful as a baseline check. |
Configuration
cua-driver config
Read and write persistent cua-driver settings.
Persistent config lives at
~/Library/Application Support/<app-name>/config.json and
survives daemon restarts.
Examples: cua-driver config # print full config cua-driver config get agent_cursor.enabled cua-driver config set agent_cursor.enabled false cua-driver config set agent_cursor.motion.arc_size 0.4 cua-driver config reset # overwrite with defaults
cua-driver config show
Print the full current config as JSON.
cua-driver config get
Print a single config value by key.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
<key> | String | Yes | Config key to read (e.g. schema_version, agent_cursor.enabled). |
cua-driver config set
Write a single config value by dotted snake_case key.
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
<key> | String | Yes | Dotted snake_case path, e.g. agent_cursor.enabled or agent_cursor.motion.arc_size. |
<value> | String | Yes | New value. JSON type depends on the key. |
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--socket | String | — | Override the daemon Unix socket path. |
cua-driver config reset
Overwrite the config file with defaults.
cua-driver config telemetry
Manage anonymous telemetry settings.
cua-driver config telemetry status
Show whether anonymous telemetry is enabled.
cua-driver config telemetry enable
Enable anonymous telemetry.
cua-driver config telemetry disable
Disable anonymous telemetry.
cua-driver config updates
Manage automatic update settings.
cua-driver config updates status
Show whether automatic updates are enabled.
cua-driver config updates enable
Enable automatic updates.
cua-driver config updates disable
Disable automatic updates.
Diagnostics
cua-driver update
Check for a newer cua-driver release and apply it.
Flags:
| Name | Description |
|---|---|
--apply | Download and apply the update without prompting. |
cua-driver diagnose
Print a paste-able bundle-path / cdhash / TCC-status report for support.
cua-driver doctor
Clean up stale install bits left from older cua-driver versions.
Other commands
cua-driver dump-docs
Output CLI and MCP tool documentation as JSON for tooling and integrations.
Options:
| Name | Type | Default | Description |
|---|---|---|---|
--type | String | all | Documentation type: cli, mcp, or all |
Flags:
| Name | Description |
|---|---|
--pretty | Pretty-print JSON output |
Global options
Available on all commands:
--help— Show help information.--version— Show version number.
Was this page helpful?