TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/trycua/cua/llms.txt
Use this file to discover all available pages before exploring further.
cua-driver binary is the cross-platform computer-use automation driver. Install it via the official script and use it to start an MCP server, run a long-lived daemon, invoke tools from the shell, or manage diagnostics and configuration.
cua-driver --version to confirm your installed version. The macOS-only cua-driver permissions command is documented in the macOS Requirements section of the Platform Support page.
Tool Dispatch
These commands let you discover and invoke MCP tools without a running MCP session.cua-driver list-tools
List every registered MCP tool with a one-line description. Useful for confirming which tools are available in the installed version without starting a daemon.
cua-driver describe <tool-name>
Print a tool’s full description and its JSON input schema.
Name of the MCP tool to describe (snake_case, e.g.
get_window_state).cua-driver call <tool-name> [<json-args>]
Invoke an MCP tool through the running daemon and print the result. JSON arguments may be passed as a positional argument or piped through stdin. Requires a running cua-driver serve daemon.
Name of the MCP tool to invoke.
JSON object matching the tool’s input schema. When omitted, stdin is read if
it is a pipe.
Write the first image content block from the response to this file path
instead of embedding it in stdout.
Override the daemon socket or named-pipe path used to reach the running
daemon.
Daemon Management
cua-driver mcp
Run the stdio MCP server. This is the primary entry point for MCP-capable agents. On Windows and Linux, the bare cua-driver mcp process owns the runtime directly and shuts it down when stdin reaches EOF. On macOS it proxies to the installed CuaDriver.app daemon so Accessibility and Screen Recording grants retain the app-bundle identity.
Connect to an explicit daemon socket or named-pipe endpoint instead of
auto-discovering one.
Advisory bundle ID label echoed in
check_permissions output. Used in
embedded mode to identify the hosting application.Select an installed cursor theme ID for the agent cursor overlay.
Controls cursor animation. Accepts
auto (follow OS setting), on (force
still frames), or off (allow animation).Pre-authorize a residual standard-mode boundary for a newly launched runtime.
Repeatable. Currently supported value:
existing-profile.Own the runtime in this MCP process rather than proxying to a daemon. On
macOS, TCC attribution follows the spawning host. Mutually exclusive with
--socket.Compatibility flag for older Claude Code setup snippets. Removes the
standalone
screenshot tool; use get_window_state for window screenshots.Declare embedding-host mode. Without
--direct, requires the host’s private
service through --socket instead of auto-launching the standalone app.cua-driver serve
Run cua-driver as a long-lived daemon. The daemon owns per-process state such as element-index caches, recording state, and cursor overlay state. Clients (MCP proxies, CLI calls, SDK connections) connect over a local IPC endpoint.
Override the daemon socket or named-pipe path.
Override the pid-file path on Unix targets.
Immutable agent authorization mode. Accepts
standard, bounded, or
unrestricted. Fixed at launch; restart the daemon to change it.Pre-authorize a residual standard-mode boundary. Repeatable; supported
value:
existing-profile.Path to the tool manifest file required in
bounded mode.Advisory host bundle ID label for embedded mode.
Select
unrestricted mode and acknowledge its risk. Required alongside
--permission-mode unrestricted.Trusted-launcher confirmation that the exact bounded manifest was reviewed.
Required in
bounded mode alongside --session-policy.Skip the macOS first-launch permissions gate.
Run embedded inside a host app: inherit the host’s TCC grants, never prompt
or relaunch. Equivalent to setting
CUA_DRIVER_EMBEDDED=1.Disable the agent cursor overlay for this daemon.
cua-driver stop
Ask the running daemon to exit gracefully.
Override the daemon socket or named-pipe path.
cua-driver status
Report whether a cua-driver daemon is currently running and reachable.
Override the daemon socket or named-pipe path.
Override the pid-file path on Unix targets.
cua-driver mcp-config
Print client-specific connection guidance, including an MCP config snippet where the client supports it. Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode.
Client name to generate configuration for (e.g.
claude).Trajectory Recording
Recording state lives in the daemon and survives client reconnects. Turn folders are written asturn-00001/, turn-00002/, etc.
cua-driver recording start <output-dir>
Start trajectory recording to a directory.
Directory where turn folders will be written.
cua-driver recording stop
Stop trajectory recording.
cua-driver recording status
Print the current recording state.
cua-driver recording render <input-dir> <out-mp4>
Render a previously recorded trajectory directory to an MP4. This is a pure file-to-file path that does not require a running daemon.
Trajectory directory containing recorded turn folders.
Output MP4 file path.
Scale factor applied to rendered frames.
Disable cursor and action zoom effects in the rendered video.
Configuration
cua-driver config
Read or mutate persistent driver configuration. Without a subcommand, prints the full config.
Override the daemon socket or named-pipe path.
| Subcommand | Description |
|---|---|
config show | Print the full config. |
config get <key> | Print one config key. |
config set <key> <value> | Set one config key. |
config reset | Reset config to defaults. |
Diagnostics
cua-driver check-update
Check whether a newer cua-driver release is available on GitHub. Read-only — never installs. Uses the same payload as the check_for_update MCP tool.
Emit a machine-readable JSON payload.
Skip the 20-hour on-disk cache and force a live GitHub request.
cua-driver update
Check for an update and optionally apply it. The apply path delegates to the canonical platform installer scripts.
Download and install the latest release when one is available.
Emit the structured update-state payload.
cua-driver doctor
Run platform-aware diagnostic probes. Exit code is non-zero when any probe reports an error.
Emit the probe report as JSON.
cua-driver diagnose
Print a pasteable install-layout and permission-attribution report. Useful for bug reports and support tickets.
Other Commands
cua-driver revoke
Revoke one or all live authorization or session scopes. Revocation is deny-only and never accepts an approval token.
Exact session ID to stop and revoke.
Stop and revoke every live session.
Override the daemon socket or named-pipe path.
cua-driver autostart
Manage platform-native daemon autostart. On Windows, registers a logon Scheduled Task. On macOS and Linux, prints manual-recipe guidance.
| Subcommand | Description |
|---|---|
autostart enable | Register the autostart entry. |
autostart disable | Remove the autostart entry. |
autostart status | Print whether autostart is registered and running. |
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.
| Subcommand | Key options | Description |
|---|---|---|
skills install | --agent <name>, --from <source>, --all-platforms | Fetch the versioned skill pack and link detected agents. |
skills update | — | Refresh the local skill pack and links. |
skills uninstall | --all | Remove agent skill links. --all also deletes the local skill-pack copy. |
skills status | — | Report local skill-pack and per-agent link state. |
skills path | — | Print the local skill-pack path. |
cua-driver telemetry
Inspect or change content-free product telemetry. Telemetry is default-on. Disabling it retains the pseudonymous installation ID; reset-id erases the ID and event markers while preserving the preference.
| Subcommand | Description |
|---|---|
telemetry enable | Persistently enable telemetry. |
telemetry disable | Persistently disable every telemetry request. |
telemetry status [--json] | Show the effective setting and redacted identity state. |
telemetry reset-id | Erase the installation ID and event markers. |
telemetry inspect <event> [--json] | Build a fixed event payload without sending it. |
cua-driver permissions (macOS only)
Inspect or request the macOS TCC grants the driver needs (Accessibility and Screen Recording).
This command has no Windows or Linux counterpart. Embedded-mode hosts do not
use
permissions grant; the host app requests grants itself.Machine-readable status output.
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.
Pretty-print JSON output.
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.
| Subcommand | Description |
|---|---|
cursor-theme validate <source> | Validate a bounded dotLottie source archive. |
cursor-theme build <source> | Compile a validated .lottie archive into a .cua-theme artifact. |
cursor-theme inspect <theme> | Inspect metadata in a compiled .cua-theme artifact. |
cursor-theme preview <theme> | Render a compiled theme’s still frames to a directory. |
cursor-theme install <theme> | Install a compiled theme into the current user’s theme store. |
cursor-theme list | List built-in and installed cursor themes. |
cursor-theme uninstall <theme-id> | Remove a custom theme from the theme store. The built-in cua.default cannot be removed. |
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.
Which docs to emit:
all, cli, or mcp.Pretty-print JSON output.
Global Options
The following flags are available on every command:| Flag | Description |
|---|---|
--help | Show help information for the command. |
--version | Show the installed cua-driver version number. |