Serve, configure and update
Serve MCP and call tools from the shell; run the daemon; grant permissions and diagnose; configure the driver, telemetry and cursor; update and pick a release channel.
| Command | Description |
|---|---|
cua-driver mcp | Run the stdio MCP server. |
cua-driver connect | Connect Claude Code, Codex, Cursor and Factory Droid to Cua Driver: add it to each agent that is installed and install the skill pack. |
cua-driver mcp-config | Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent. |
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. |
cua-driver call | Invoke an MCP tool through the running daemon. |
cua-driver manifest | Emit a stable JSON description of the CLI surface. |
cua-driver dump-docs | Output machine-readable CLI and MCP documentation JSON. |
cua-driver serve | Run Cua Driver as a long-running daemon. |
cua-driver stop | Ask the running daemon to exit gracefully. |
cua-driver status | Report whether a Cua Driver daemon is running. |
cua-driver sessions | List content-free lifecycle summaries for sessions owned by the daemon runtime. |
cua-driver sessions list | List live sessions. |
cua-driver revoke | Revoke one or all live authorization/session scopes. |
cua-driver autostart | Manage platform-native daemon autostart. |
cua-driver autostart enable | Register the autostart entry. |
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 permissions | Inspect or raise macOS TCC permission grants (macOS only). |
cua-driver permissions status | Show whether Cua Driver can use your mouse and keyboard (Accessibility) and see your screen (Screen Recording), read-only and without prompts. |
cua-driver permissions grant | Walk through the Accessibility and Screen Recording switches one at a time, then confirm with a test screenshot. |
cua-driver kwin-capture | Turn exact KWin window capture and activation on or off (Linux). |
cua-driver kwin-capture status | Show the setting and the desktop entry. |
cua-driver kwin-capture on | Turn it on; on KWin 6.7 and older also write the desktop entry KWin checks. |
cua-driver kwin-capture off | Turn it off and remove the desktop entry. |
cua-driver doctor | Run platform-aware diagnostic probes. |
cua-driver diagnose | Print a pasteable install-layout and permission-attribution report. |
cua-driver test | Check that Cua Driver works on this computer. |
cua-driver config | Read or mutate persistent driver configuration. |
cua-driver config show | Print the full config. |
cua-driver config get | Print one config key. |
cua-driver config set | Set one config key. |
cua-driver config reset | Reset config to defaults. |
cua-driver telemetry | Inspect or change content-free product telemetry. |
cua-driver telemetry enable | Persistently enable telemetry. |
cua-driver telemetry disable | Persistently disable every telemetry request. |
cua-driver telemetry status | Show the effective setting and redacted identity state. |
cua-driver telemetry reset-id | Erase the installation ID and event markers. |
cua-driver telemetry inspect | Build a fixed event payload without sending it. |
cua-driver cursor-theme | Validate, compile, inspect, preview, install, or remove a local cursor theme. |
cua-driver cursor-theme validate | Validate a bounded dotLottie source archive. |
cua-driver cursor-theme build | Compile a validated dotLottie archive into a bounded .cua-theme artifact. |
cua-driver cursor-theme inspect | Inspect metadata in a compiled .cua-theme artifact. |
cua-driver cursor-theme preview | Render a compiled theme's representative still frames to a directory. |
cua-driver cursor-theme install | Install a compiled theme into the current user's theme store. |
cua-driver cursor-theme list | List the built-in and installed cursor themes. |
cua-driver cursor-theme uninstall | Remove a custom theme from the current user's theme store. |
cua-driver cursor | Configure a session's agent cursor from the command line. |
cua-driver cursor motion | Set the cursor's motion style, timing and effects. |
cua-driver check-update | Check whether a newer cua-driver release is available. |
cua-driver update | Check for an update and optionally apply it. |
cua-driver channel | Inspect or change the stable/nightly update channel. |
cua-driver channel status | Show selected and current release channels. |
cua-driver channel set | Save stable or nightly as the update channel. |
Every command also accepts the global options.
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.
cua-driver mcp [OPTIONS]| Flag | 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. | |
--direct | boolean | false | Own the runtime in this MCP process; mutually exclusive with --socket. |
--claude-code-computer-use-compat | boolean | false | Accepted for older Claude Code setup snippets; there is no standalone screenshot tool; use get_window_state for window screenshots. |
--embedded | boolean | false | Declare embedding-host mode. Without --direct, require the host's private service through --socket instead of auto-launching the standalone app. |
Examples
# Run the stdio MCP server (what MCP clients launch)
cua-driver mcp
# Connect to a daemon on an explicit socket
cua-driver mcp --socket /tmp/cua-driver.sockcua-driver connect#
Connect Claude Code, Codex, Cursor and Factory Droid to Cua Driver: add it to each agent that is installed and install the skill pack.
Registers one server named cua-driver with each agent found (through the agent's own CLI, or by merging into Cursor's or Droid's mcp.json without touching other entries) and installs the skill pack. For Droid it also rates each action tool medium in ~/.factory/settings.json, so droid exec --auto medium runs them. An agent already connected, including under the older Claude Code name cua-computer-use, is left alone, so it is safe to run again. An agent whose cua-driver server launches a different Cua Driver, such as the one inside Cua Spaces, is reported as using another Cua Driver and left as is; --replace switches Claude Code, Codex and Cursor to this one the way Set up in Cua Spaces does, backing up the config file first. One agent failing does not stop the others; the exit code is non-zero only when an agent was found and none could be connected.
cua-driver connect [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--client | string | Connect only this agent (claude, codex, cursor or droid). Repeat for several. | |
--dry-run | boolean | false | Show what would be connected without changing anything. |
--replace | boolean | false | Switch an agent that uses another Cua Driver, such as the one inside Cua Spaces, to this one. |
--json | boolean | false | Emit machine-readable output. |
Examples
# Connect every agent found on this computer
cua-driver connect
# Show what would change for Claude Code
cua-driver connect --client claude --dry-run
# Print the result for each agent as JSON
cua-driver connect --json
# Switch agents that use another Cua Driver to this one
cua-driver connect --replacecua-driver mcp-config#
Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent.
Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, zcode, and deepseek-harness. With --client, the cua-driver skill pack is also installed for that agent (not for qwen, droid or zcode, which have no skills folder), and one line on stderr says where; --no-skills skips it.
cua-driver mcp-config [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--client | string | Client name to print configuration for. | |
--no-skills | boolean | false | With --client, do not install the cua-driver skill pack for that agent. |
Examples
# Print a generic mcpServers entry
cua-driver mcp-config
# Print setup for Codex and install its skill pack
cua-driver mcp-config --client codex
# Print setup for Codex only
cua-driver mcp-config --client codex --no-skillscua-driver list-tools#
List every registered MCP tool with a one-line description.
cua-driver list-toolsExamples
# List every tool with a one-line description
cua-driver list-toolscua-driver describe#
Print a tool's full description and JSON input schema.
cua-driver describe <tool-name>| Argument | Type | Default | Description |
|---|---|---|---|
<tool-name> | string | required | Name of the MCP tool to describe. |
Examples
# Print a tool's description and input schema
cua-driver describe clickcua-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.
cua-driver call [OPTIONS] <tool-name> [<json-args>]| Argument | Type | Default | Description |
|---|---|---|---|
<tool-name> | string | required | Name of the MCP tool to invoke. |
<json-args> | string | optional | JSON object for the tool input schema. If omitted, stdin is read when piped. |
| Flag | Type | Default | Description |
|---|---|---|---|
--screenshot-out-file | path | Write the first image content block from the response to this path. | |
--socket | string | Override the daemon socket or named-pipe path. |
Examples
# Call a tool with no arguments
cua-driver call list_apps
# Click at window coordinates
cua-driver call click '{"pid":844,"x":100,"y":200}'
# Save the screenshot from a tool response
cua-driver call get_window_state '{"pid":844,"window_id":10725}' --screenshot-out-file state.png
# Read only what changed since an earlier snapshot_id
cua-driver call get_window_state '{"pid":844,"window_id":10725,"since":"s0000002a"}'
# Return the structured elements instead of the markdown tree
cua-driver call get_window_state '{"pid":844,"window_id":10725,"tree_format":"elements"}'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.
cua-driver manifest [OPTIONS]| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--pretty | -p | boolean | false | Pretty-print JSON. |
Examples
# Print the CLI surface as JSON
cua-driver manifest --prettycua-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.
cua-driver dump-docs [OPTIONS]| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--type | string | all | Which docs to emit: all, cli, or mcp. | |
--pretty | -p | boolean | false | Pretty-print JSON. |
Examples
# Print the CLI documentation JSON
cua-driver dump-docs --type cli --prettycua-driver serve#
Run Cua Driver as a long-running daemon.
The daemon owns per-process state such as accessibility snapshots, recording state, and cursor overlay state.
cua-driver serve [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. | |
--pid-file | path | Override the pid-file path. | |
--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. | |
--capability-manifest | path | Optional narrow-only tool/resource ceiling; required in bounded mode. | |
--session-policy | path | Deprecated alias for capability-manifest. | |
--host-bundle-id | string | Advisory host bundle id label echoed in check_permissions output (embedded mode). | |
--cursor-theme | string | cua.default | Installed cursor theme id for the agent cursor overlay. |
--cursor-reduced-motion | string | auto | Agent cursor motion: auto follows the OS setting, on forces still frames, off allows animation. |
--glide-ms | number | Override the agent cursor glide duration, in milliseconds. | |
--dwell-ms | number | Override how long the agent cursor dwells after a click, in milliseconds. | |
--idle-hide-ms | number | Override how long an idle agent cursor stays visible, in milliseconds. | |
--claude-code-computer-use-compat | boolean | false | Legacy compatibility flag forwarded by mcp when it launches the daemon; no current tool-surface effect. |
--dangerously-bypass-approvals | boolean | false | Select unrestricted mode and acknowledge its risk. |
--approve-capability-manifest | boolean | false | Trusted-launcher confirmation that the exact capability manifest was reviewed. |
--approve-session-policy | boolean | false | Deprecated alias for approve-capability-manifest. |
--no-permissions-gate | boolean | false | Skip the macOS first-launch permissions gate. |
--no-automation-prompts | boolean | false | Refuse scripting actions without granted macOS Automation consent. |
--embedded | boolean | false | Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1. |
--no-overlay | boolean | false | Disable the agent cursor overlay for this daemon. |
--experimental-history | boolean | false | Admit the encrypted local Computer History early preview for this daemon launch. |
Examples
# Run the daemon in the foreground
cua-driver serve
# Start a bounded daemon with a reviewed capability manifest
cua-driver serve --permission-mode bounded --capability-manifest manifest.yaml --approve-capability-manifest
# Run without the agent cursor overlay
cua-driver serve --no-overlaycua-driver stop#
Ask the running daemon to exit gracefully.
cua-driver stop [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. | |
--expected-pid | number | Stop only if the daemon's process id is this one (a positive integer). |
Examples
# Ask the running daemon to exit
cua-driver stopcua-driver status#
Report whether a Cua Driver daemon is running.
cua-driver status [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. | |
--pid-file | path | Override the pid-file path. |
Examples
# Check whether the daemon is running
cua-driver statuscua-driver sessions#
List content-free lifecycle summaries for sessions owned by the daemon runtime.
cua-driver sessions [OPTIONS] [COMMAND]Without a subcommand, runs cua-driver sessions list.
| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. | |
--json | boolean | false | Emit the machine-readable session summary. |
Examples
# List live sessions as JSON
cua-driver sessions --jsoncua-driver sessions list#
List live sessions. The default subcommand.
cua-driver sessions listExamples
# List live sessions
cua-driver sessions listcua-driver revoke#
Revoke one or all live authorization/session scopes.
Revocation is deny-only and never accepts an approval token.
cua-driver revoke [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--session | string | Exact session id to stop and revoke. | |
--socket | string | Override the daemon socket or named-pipe path. | |
--all | boolean | false | Stop and revoke every live session. |
Examples
# Stop and revoke one session
cua-driver revoke --session 3f9c2a
# Stop and revoke every live session
cua-driver revoke --allcua-driver autostart#
Manage platform-native daemon autostart.
Windows registers a logon Scheduled Task. macOS and Linux currently print manual-recipe guidance.
cua-driver autostart <COMMAND>Examples
# Check the autostart entry
cua-driver autostart statuscua-driver autostart enable#
Register the autostart entry.
cua-driver autostart enableExamples
# Start the daemon at every logon
cua-driver autostart enablecua-driver autostart disable#
Remove the autostart entry.
cua-driver autostart disableExamples
# Remove the autostart entry
cua-driver autostart disablecua-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 statusExamples
# Check the autostart entry
cua-driver autostart statuscua-driver autostart kick#
Start the autostart entry now without re-logging.
cua-driver autostart kickExamples
# Start the entry now
cua-driver autostart kickcua-driver permissions#
cua-driver permissions exists on macOS only; Windows and Linux have no TCC equivalent.
permissions statusis read-only and never prompts. It does not run the ScreenCaptureKit probe (macOS Tahoe can show a separate dialog for it), so it reportsscreen_recording_capturable: nullanddirect_capture_status: "not_checked", plus the last successfulpermissions grantverification when one is recorded for the running driver identity.permissions grantlaunches the installedCuaDriver.appthrough LaunchServices so the prompts attribute to the app, then requires a successful live capture probe. It never sends a prompt-capable request over the daemon socket.- Embedded hosts, in-process
CuaDriver.create()runtimes andcua-driver mcp --directown their own prompts: there,check_permissionsstays read-only even with{"prompt": true}. - After a grant changes, quit and relaunch the responsible app (
CuaDriver.app, or the host of a direct runtime).
See Permissions for the grant flow and recovery.
Inspect or raise macOS TCC permission grants (macOS only).
macOS only: Accessibility and Screen Recording are macOS TCC grants. See the macOS permissions reference.
cua-driver permissions [COMMAND]Without a subcommand, runs cua-driver permissions status.
Examples
# Report Accessibility and Screen Recording status
cua-driver permissionscua-driver permissions status#
Show whether Cua Driver can use your mouse and keyboard (Accessibility) and see your screen (Screen Recording), read-only and without prompts. The default subcommand.
cua-driver permissions status [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit machine-readable output. |
Examples
# Report the grants as JSON
cua-driver permissions status --jsoncua-driver permissions grant#
Walk through the Accessibility and Screen Recording switches one at a time, then confirm with a test screenshot.
cua-driver permissions grantExamples
# Request the grants for CuaDriver.app
cua-driver permissions grantcua-driver kwin-capture#
Turn exact KWin window capture and activation on or off (Linux).
Off by default on every KWin release. The setting is read on every call, so no restart is needed; on waits up to about five seconds for KWin to grant it on KWin 6.7 and older, then prints the status line either way. Only this command changes it; set_config cannot.
cua-driver kwin-capture [COMMAND]Without a subcommand, runs cua-driver kwin-capture status.
Examples
# Show whether exact KWin window capture is on
cua-driver kwin-capturecua-driver kwin-capture status#
Show the setting and the desktop entry. The default subcommand.
cua-driver kwin-capture statusExamples
# Show the setting and the desktop entry
cua-driver kwin-capture statuscua-driver kwin-capture on#
Turn it on; on KWin 6.7 and older also write the desktop entry KWin checks.
A screenshot Deny saved in the desktop portal keeps it off unless --override-portal-deny is given.
cua-driver kwin-capture on [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--override-portal-deny | boolean | false | Ignore a screenshot Deny saved in the desktop portal. |
Examples
# Turn exact KWin window capture on
cua-driver kwin-capture oncua-driver kwin-capture off#
Turn it off and remove the desktop entry.
cua-driver kwin-capture offExamples
# Turn exact KWin window capture off
cua-driver kwin-capture offcua-driver doctor#
Run platform-aware diagnostic probes.
Exit code is non-zero when any probe is an error. On macOS it warns about other copies of CuaDriver.app that macOS can launch instead of the installed one, and about permission rows tied to a different path or version.
cua-driver doctor [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit the probe report as JSON. |
--fix | boolean | false | macOS: make LaunchServices forget every other copy of CuaDriver.app. No files are deleted. |
Examples
# Run the diagnostic probes
cua-driver doctor
# Emit the probe report as JSON
cua-driver doctor --json
# macOS: make macOS forget extra copies of the app (deletes no files)
cua-driver doctor --fixcua-driver diagnose#
Print a pasteable install-layout and permission-attribution report.
cua-driver diagnoseExamples
# Print an install and permission report to paste into an issue
cua-driver diagnosecua-driver test#
Check that Cua Driver works on this computer.
Checks permissions, a screen read, Cua Driver's own pointer, and (macOS) typing in a background TextEdit window that is closed without saving. Exit code is 0 when everything works and 1 when something needs fixing.
cua-driver test [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit the result as JSON. |
Examples
# Check that Cua Driver works on this computer
cua-driver test
# Emit the result as JSON
cua-driver test --jsoncua-driver config#
Read or mutate persistent driver configuration.
Without a subcommand, prints the full config.
cua-driver config [OPTIONS] [COMMAND]Without a subcommand, runs cua-driver config show.
| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. |
Examples
# Print the full config
cua-driver configcua-driver config show#
Print the full config.
cua-driver config showExamples
# Print the full config
cua-driver config showcua-driver config get#
Print one config key.
cua-driver config get <key>| Argument | Type | Default | Description |
|---|---|---|---|
<key> | string | required | Config key to read. |
Examples
# Print one key
cua-driver config get max_image_dimensioncua-driver config set#
Set one config key.
Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.<trail|glow|magnet|ripple|squish> (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default. cursor.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default. cursor.float (float at rest and while moving) and cursor.halo (soft glow) are on, off or default and on by default; cursor.rotate is heading (default), lean, off or default. All apply to every cursor at once.
cua-driver config set <key> <value>| Argument | Type | Default | Description |
|---|---|---|---|
<key> | string | required | Config key to write. |
<value> | string | required | Value to store. |
Examples
# Downscale screenshots to at most 1568 px
cua-driver config set max_image_dimension 1568
# Make magnetic the default cursor motion for new sessions
cua-driver config set cursor.motion.style magnetic
# Scale cursor move time with distance and target size
cua-driver config set cursor.motion.timing fitts
# Drop the 600 ms floor of the default steady timing
cua-driver config set cursor.motion.timing native
# Turn the cursor trail on by default
cua-driver config set cursor.motion.effects.trail truecua-driver config reset#
Reset config to defaults.
cua-driver config resetExamples
# Restore the defaults
cua-driver config resetcua-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 <COMMAND>Examples
# Show the effective telemetry setting
cua-driver telemetry statuscua-driver telemetry enable#
Persistently enable telemetry.
cua-driver telemetry enableExamples
# Enable telemetry
cua-driver telemetry enablecua-driver telemetry disable#
Persistently disable every telemetry request.
Retains the local installation ID.
cua-driver telemetry disableExamples
# Disable every telemetry request
cua-driver telemetry disablecua-driver telemetry status#
Show the effective setting and redacted identity state.
cua-driver telemetry status [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit JSON. |
Examples
# Show the setting as JSON
cua-driver telemetry status --jsoncua-driver telemetry reset-id#
Erase the installation ID and event markers.
The persisted enabled/disabled preference is retained.
cua-driver telemetry reset-idExamples
# Erase the installation ID
cua-driver telemetry reset-idcua-driver telemetry inspect#
Build a fixed event payload without sending it.
The distinct ID is replaced with a redacted placeholder.
cua-driver telemetry inspect [OPTIONS] <event>| Argument | Type | Default | Description |
|---|---|---|---|
<event> | string | required | Fixed telemetry event name. |
| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit JSON (the only output format; pass it for forward compatibility). |
Examples
# Show the payload of one event without sending it
cua-driver telemetry inspect cua_driver_cli_completed --jsoncua-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 <COMMAND>Examples
# List cursor themes
cua-driver cursor-theme listcua-driver cursor-theme validate#
Validate a bounded dotLottie source archive.
cua-driver cursor-theme validate [OPTIONS] <source>| Argument | Type | Default | Description |
|---|---|---|---|
<source> | path | required | Path to the source .lottie archive. |
| Flag | Type | Default | Description |
|---|---|---|---|
--development | boolean | false | Allow the reserved com.example development namespace. |
Examples
# Validate a source archive
cua-driver cursor-theme validate my-cursor.lottiecua-driver cursor-theme build#
Compile a validated dotLottie archive into a bounded .cua-theme artifact.
cua-driver cursor-theme build [OPTIONS] <source>| Argument | Type | Default | Description |
|---|---|---|---|
<source> | path | required | Path to the source .lottie archive. |
| Flag | Type | Default | Description |
|---|---|---|---|
--output | path | required | Output .cua-theme path. |
--development | boolean | false | Allow the reserved com.example development namespace. |
Examples
# Compile a theme
cua-driver cursor-theme build my-cursor.lottie --output my-cursor.cua-themecua-driver cursor-theme inspect#
Inspect metadata in a compiled .cua-theme artifact.
cua-driver cursor-theme inspect [OPTIONS] <theme>| Argument | Type | Default | Description |
|---|---|---|---|
<theme> | path | required | Path to the compiled .cua-theme artifact. |
| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit machine-readable JSON. |
Examples
# Print a theme's metadata
cua-driver cursor-theme inspect my-cursor.cua-theme --jsoncua-driver cursor-theme preview#
Render a compiled theme's representative still frames to a directory.
cua-driver cursor-theme preview [OPTIONS] <theme>| Argument | Type | Default | Description |
|---|---|---|---|
<theme> | path | required | Path to the compiled .cua-theme artifact. |
| Flag | Type | Default | Description |
|---|---|---|---|
--output | path | required | Preview output directory. |
Examples
# Render still frames
cua-driver cursor-theme preview my-cursor.cua-theme --output previewcua-driver cursor-theme install#
Install a compiled theme into the current user's theme store.
cua-driver cursor-theme install <theme>| Argument | Type | Default | Description |
|---|---|---|---|
<theme> | path | required | Path to the compiled .cua-theme artifact. |
Examples
# Install a theme
cua-driver cursor-theme install my-cursor.cua-themecua-driver cursor-theme list#
List the built-in and installed cursor themes.
cua-driver cursor-theme list [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit machine-readable JSON. |
Examples
# List themes as JSON
cua-driver cursor-theme list --jsoncua-driver cursor-theme uninstall#
Remove a custom theme from the current user's theme store.
The built-in cua.default theme cannot be removed.
cua-driver cursor-theme uninstall <theme-id>| Argument | Type | Default | Description |
|---|---|---|---|
<theme-id> | string | required | Installed custom theme id. |
Examples
# Remove an installed theme
cua-driver cursor-theme uninstall com.example.my-cursorcua-driver cursor#
Configure a session's agent cursor from the command line.
Forwards to the set_agent_cursor_motion tool on the running daemon. Fields you leave out keep their current value.
cua-driver cursor <COMMAND>Examples
# Use the magnetic cursor motion
cua-driver cursor motion --session demo --style magneticcua-driver cursor motion#
Set the cursor's motion style, timing and effects.
Effects take on, off, or default (the style's own choice).
cua-driver cursor motion [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--session | string | required | Public label of the session that owns the cursor. |
--style | string | signature_arc, spring_settle, magnetic, comet_swoop, adaptive, or classic. | |
--timing | string | native, fitts, or fixed. | |
--effects | string | Comma-separated name=on|off|default for trail, glow, magnet, ripple, squish. | |
--glide-ms | number | Move duration in milliseconds for fixed timing (1430 when 0). | |
--socket | path | Override the daemon socket path. |
Examples
# Use the comet swoop cursor motion
cua-driver cursor motion --session demo --style comet_swoop
# Make every move take 900 ms
cua-driver cursor motion --session demo --timing fixed --glide-ms 900
# Turn off the trail and reset the click ripple
cua-driver cursor motion --session demo --effects trail=off,ripple=defaultcua-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.
cua-driver check-update [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit a machine-readable JSON payload. |
--no-cache | boolean | false | Skip the 1-hour on-disk cache and look up the latest release again. |
Examples
# Check for a newer release
cua-driver check-update
# Check now, as JSON
cua-driver check-update --json --no-cachecua-driver update#
Check for an update and optionally apply it.
The apply path delegates to the canonical platform installer scripts.
cua-driver update [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--apply | boolean | false | Download and install the latest release when one is available. |
--json | boolean | false | Emit the structured update-state payload. |
Examples
# Check and print the install command
cua-driver update
# Install the latest release
cua-driver update --applycua-driver channel#
Inspect or change the stable/nightly update channel.
Selection is persistent but never installs by itself; use cua-driver update --apply after changing it.
cua-driver channel [COMMAND]Without a subcommand, runs cua-driver channel status.
Examples
# Show the selected release channel
cua-driver channelcua-driver channel status#
Show selected and current release channels.
cua-driver channel status [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit machine-readable channel state. |
Examples
# Show the channels as JSON
cua-driver channel status --jsoncua-driver channel set#
Save stable or nightly as the update channel.
cua-driver channel set [OPTIONS] <channel>| Argument | Type | Default | Description |
|---|---|---|---|
<channel> | string | required | Release channel: stable or nightly. |
| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Emit machine-readable channel state. |
Examples
# Follow nightly builds (then run update --apply)
cua-driver channel set nightlyExit codes#
| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. call and direct tool invocations exit with the daemon's result code (1 on a tool error); update --apply passes through the installer's status. |
2 | Invalid input: tool arguments that are not valid JSON, an unknown mcp-config client, or an update --apply refused on a local development install. |
64 | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example revoke without exactly one of --session or --all, or an authorization flag passed to mcp). |