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.

CommandDescription
cua-driver mcpRun the stdio MCP server.
cua-driver connectConnect 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-configPrint client-specific connection guidance (MCP config where supported) and install the skill pack for that agent.
cua-driver list-toolsList every registered MCP tool with a one-line description.
cua-driver describePrint a tool's full description and JSON input schema.
cua-driver callInvoke an MCP tool through the running daemon.
cua-driver manifestEmit a stable JSON description of the CLI surface.
cua-driver dump-docsOutput machine-readable CLI and MCP documentation JSON.
cua-driver serveRun Cua Driver as a long-running daemon.
cua-driver stopAsk the running daemon to exit gracefully.
cua-driver statusReport whether a Cua Driver daemon is running.
cua-driver sessionsList content-free lifecycle summaries for sessions owned by the daemon runtime.
cua-driver sessions listList live sessions.
cua-driver revokeRevoke one or all live authorization/session scopes.
cua-driver autostartManage platform-native daemon autostart.
cua-driver autostart enableRegister the autostart entry.
cua-driver autostart disableRemove the autostart entry.
cua-driver autostart statusPrint whether autostart is registered and running.
cua-driver autostart kickStart the autostart entry now without re-logging.
cua-driver permissionsInspect or raise macOS TCC permission grants (macOS only).
cua-driver permissions statusShow whether Cua Driver can use your mouse and keyboard (Accessibility) and see your screen (Screen Recording), read-only and without prompts.
cua-driver permissions grantWalk through the Accessibility and Screen Recording switches one at a time, then confirm with a test screenshot.
cua-driver kwin-captureTurn exact KWin window capture and activation on or off (Linux).
cua-driver kwin-capture statusShow the setting and the desktop entry.
cua-driver kwin-capture onTurn it on; on KWin 6.7 and older also write the desktop entry KWin checks.
cua-driver kwin-capture offTurn it off and remove the desktop entry.
cua-driver doctorRun platform-aware diagnostic probes.
cua-driver diagnosePrint a pasteable install-layout and permission-attribution report.
cua-driver testCheck that Cua Driver works on this computer.
cua-driver configRead or mutate persistent driver configuration.
cua-driver config showPrint the full config.
cua-driver config getPrint one config key.
cua-driver config setSet one config key.
cua-driver config resetReset config to defaults.
cua-driver telemetryInspect or change content-free product telemetry.
cua-driver telemetry enablePersistently enable telemetry.
cua-driver telemetry disablePersistently disable every telemetry request.
cua-driver telemetry statusShow the effective setting and redacted identity state.
cua-driver telemetry reset-idErase the installation ID and event markers.
cua-driver telemetry inspectBuild a fixed event payload without sending it.
cua-driver cursor-themeValidate, compile, inspect, preview, install, or remove a local cursor theme.
cua-driver cursor-theme validateValidate a bounded dotLottie source archive.
cua-driver cursor-theme buildCompile a validated dotLottie archive into a bounded .cua-theme artifact.
cua-driver cursor-theme inspectInspect metadata in a compiled .cua-theme artifact.
cua-driver cursor-theme previewRender a compiled theme's representative still frames to a directory.
cua-driver cursor-theme installInstall a compiled theme into the current user's theme store.
cua-driver cursor-theme listList the built-in and installed cursor themes.
cua-driver cursor-theme uninstallRemove a custom theme from the current user's theme store.
cua-driver cursorConfigure a session's agent cursor from the command line.
cua-driver cursor motionSet the cursor's motion style, timing and effects.
cua-driver check-updateCheck whether a newer cua-driver release is available.
cua-driver updateCheck for an update and optionally apply it.
cua-driver channelInspect or change the stable/nightly update channel.
cua-driver channel statusShow selected and current release channels.
cua-driver channel setSave 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]
FlagTypeDefaultDescription
--socketstringSelect an explicit daemon socket or named-pipe endpoint.
--host-bundle-idstringAdvisory host bundle id label echoed in check_permissions output (embedded mode).
--cursor-themestringcua.defaultSelect an installed cursor theme id.
--cursor-reduced-motionstringautoFollow the OS setting, force still frames, or allow animation: auto, on, or off.
--grantstringPre-authorize a residual standard-mode boundary for a newly launched runtime. Repeatable; supported value: existing-profile.
--directbooleanfalseOwn the runtime in this MCP process; mutually exclusive with --socket.
--claude-code-computer-use-compatbooleanfalseAccepted for older Claude Code setup snippets; there is no standalone screenshot tool; use get_window_state for window screenshots.
--embeddedbooleanfalseDeclare 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.sock

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.

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]
FlagTypeDefaultDescription
--clientstringConnect only this agent (claude, codex, cursor or droid). Repeat for several.
--dry-runbooleanfalseShow what would be connected without changing anything.
--replacebooleanfalseSwitch an agent that uses another Cua Driver, such as the one inside Cua Spaces, to this one.
--jsonbooleanfalseEmit 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 --replace

cua-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]
FlagTypeDefaultDescription
--clientstringClient name to print configuration for.
--no-skillsbooleanfalseWith --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-skills

cua-driver list-tools#

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

cua-driver list-tools

Examples

# List every tool with a one-line description
cua-driver list-tools

cua-driver describe#

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

cua-driver describe <tool-name>
ArgumentTypeDefaultDescription
<tool-name>stringrequiredName of the MCP tool to describe.

Examples

# Print a tool's description and input schema
cua-driver describe click

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.

cua-driver call [OPTIONS] <tool-name> [<json-args>]
ArgumentTypeDefaultDescription
<tool-name>stringrequiredName of the MCP tool to invoke.
<json-args>stringoptionalJSON object for the tool input schema. If omitted, stdin is read when piped.
FlagTypeDefaultDescription
--screenshot-out-filepathWrite the first image content block from the response to this path.
--socketstringOverride 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]
FlagShortTypeDefaultDescription
--pretty-pbooleanfalsePretty-print JSON.

Examples

# Print the CLI surface as JSON
cua-driver manifest --pretty

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.

cua-driver dump-docs [OPTIONS]
FlagShortTypeDefaultDescription
--typestringallWhich docs to emit: all, cli, or mcp.
--pretty-pbooleanfalsePretty-print JSON.

Examples

# Print the CLI documentation JSON
cua-driver dump-docs --type cli --pretty

cua-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]
FlagTypeDefaultDescription
--socketstringOverride the daemon socket or named-pipe path.
--pid-filepathOverride the pid-file path.
--permission-modestringstandardImmutable agent authorization mode: standard, bounded, or unrestricted.
--grantstringPre-authorize a residual standard-mode boundary. Repeatable; supported value: existing-profile.
--capability-manifestpathOptional narrow-only tool/resource ceiling; required in bounded mode.
--session-policypathDeprecated alias for capability-manifest.
--host-bundle-idstringAdvisory host bundle id label echoed in check_permissions output (embedded mode).
--cursor-themestringcua.defaultInstalled cursor theme id for the agent cursor overlay.
--cursor-reduced-motionstringautoAgent cursor motion: auto follows the OS setting, on forces still frames, off allows animation.
--glide-msnumberOverride the agent cursor glide duration, in milliseconds.
--dwell-msnumberOverride how long the agent cursor dwells after a click, in milliseconds.
--idle-hide-msnumberOverride how long an idle agent cursor stays visible, in milliseconds.
--claude-code-computer-use-compatbooleanfalseLegacy compatibility flag forwarded by mcp when it launches the daemon; no current tool-surface effect.
--dangerously-bypass-approvalsbooleanfalseSelect unrestricted mode and acknowledge its risk.
--approve-capability-manifestbooleanfalseTrusted-launcher confirmation that the exact capability manifest was reviewed.
--approve-session-policybooleanfalseDeprecated alias for approve-capability-manifest.
--no-permissions-gatebooleanfalseSkip the macOS first-launch permissions gate.
--no-automation-promptsbooleanfalseRefuse scripting actions without granted macOS Automation consent.
--embeddedbooleanfalseRun embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1.
--no-overlaybooleanfalseDisable the agent cursor overlay for this daemon.
--experimental-historybooleanfalseAdmit 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-overlay

cua-driver stop#

Ask the running daemon to exit gracefully.

cua-driver stop [OPTIONS]
FlagTypeDefaultDescription
--socketstringOverride the daemon socket or named-pipe path.
--expected-pidnumberStop only if the daemon's process id is this one (a positive integer).

Examples

# Ask the running daemon to exit
cua-driver stop

cua-driver status#

Report whether a Cua Driver daemon is running.

cua-driver status [OPTIONS]
FlagTypeDefaultDescription
--socketstringOverride the daemon socket or named-pipe path.
--pid-filepathOverride the pid-file path.

Examples

# Check whether the daemon is running
cua-driver status

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

FlagTypeDefaultDescription
--socketstringOverride the daemon socket or named-pipe path.
--jsonbooleanfalseEmit the machine-readable session summary.

Examples

# List live sessions as JSON
cua-driver sessions --json

cua-driver sessions list#

List live sessions. The default subcommand.

cua-driver sessions list

Examples

# List live sessions
cua-driver sessions list

cua-driver revoke#

Revoke one or all live authorization/session scopes.

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

cua-driver revoke [OPTIONS]
FlagTypeDefaultDescription
--sessionstringExact session id to stop and revoke.
--socketstringOverride the daemon socket or named-pipe path.
--allbooleanfalseStop 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 --all

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

Examples

# Check the autostart entry
cua-driver autostart status

cua-driver autostart enable#

Register the autostart entry.

cua-driver autostart enable

Examples

# Start the daemon at every logon
cua-driver autostart enable

cua-driver autostart disable#

Remove the autostart entry.

cua-driver autostart disable

Examples

# Remove the autostart entry
cua-driver autostart disable

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 status

Examples

# Check the autostart entry
cua-driver autostart status

cua-driver autostart kick#

Start the autostart entry now without re-logging.

cua-driver autostart kick

Examples

# Start the entry now
cua-driver autostart kick

cua-driver permissions#

cua-driver permissions exists on macOS only; Windows and Linux have no TCC equivalent.

  • permissions status is read-only and never prompts. It does not run the ScreenCaptureKit probe (macOS Tahoe can show a separate dialog for it), so it reports screen_recording_capturable: null and direct_capture_status: "not_checked", plus the last successful permissions grant verification when one is recorded for the running driver identity.
  • permissions grant launches the installed CuaDriver.app through 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 and cua-driver mcp --direct own their own prompts: there, check_permissions stays 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 permissions

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. The default subcommand.

cua-driver permissions status [OPTIONS]
FlagTypeDefaultDescription
--jsonbooleanfalseEmit machine-readable output.

Examples

# Report the grants as JSON
cua-driver permissions status --json

cua-driver permissions grant#

Walk through the Accessibility and Screen Recording switches one at a time, then confirm with a test screenshot.

cua-driver permissions grant

Examples

# Request the grants for CuaDriver.app
cua-driver permissions grant

cua-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-capture

cua-driver kwin-capture status#

Show the setting and the desktop entry. The default subcommand.

cua-driver kwin-capture status

Examples

# Show the setting and the desktop entry
cua-driver kwin-capture status

cua-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]
FlagTypeDefaultDescription
--override-portal-denybooleanfalseIgnore a screenshot Deny saved in the desktop portal.

Examples

# Turn exact KWin window capture on
cua-driver kwin-capture on

cua-driver kwin-capture off#

Turn it off and remove the desktop entry.

cua-driver kwin-capture off

Examples

# Turn exact KWin window capture off
cua-driver kwin-capture off

cua-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]
FlagTypeDefaultDescription
--jsonbooleanfalseEmit the probe report as JSON.
--fixbooleanfalsemacOS: 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 --fix

cua-driver diagnose#

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

cua-driver diagnose

Examples

# Print an install and permission report to paste into an issue
cua-driver diagnose

cua-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]
FlagTypeDefaultDescription
--jsonbooleanfalseEmit the result as JSON.

Examples

# Check that Cua Driver works on this computer
cua-driver test
 
# Emit the result as JSON
cua-driver test --json

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

FlagTypeDefaultDescription
--socketstringOverride the daemon socket or named-pipe path.

Examples

# Print the full config
cua-driver config

cua-driver config show#

Print the full config.

cua-driver config show

Examples

# Print the full config
cua-driver config show

cua-driver config get#

Print one config key.

cua-driver config get <key>
ArgumentTypeDefaultDescription
<key>stringrequiredConfig key to read.

Examples

# Print one key
cua-driver config get max_image_dimension

cua-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>
ArgumentTypeDefaultDescription
<key>stringrequiredConfig key to write.
<value>stringrequiredValue 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 true

cua-driver config reset#

Reset config to defaults.

cua-driver config reset

Examples

# Restore the defaults
cua-driver config reset

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

Examples

# Show the effective telemetry setting
cua-driver telemetry status

cua-driver telemetry enable#

Persistently enable telemetry.

cua-driver telemetry enable

Examples

# Enable telemetry
cua-driver telemetry enable

cua-driver telemetry disable#

Persistently disable every telemetry request.

Retains the local installation ID.

cua-driver telemetry disable

Examples

# Disable every telemetry request
cua-driver telemetry disable

cua-driver telemetry status#

Show the effective setting and redacted identity state.

cua-driver telemetry status [OPTIONS]
FlagTypeDefaultDescription
--jsonbooleanfalseEmit JSON.

Examples

# Show the setting as JSON
cua-driver telemetry status --json

cua-driver telemetry reset-id#

Erase the installation ID and event markers.

The persisted enabled/disabled preference is retained.

cua-driver telemetry reset-id

Examples

# Erase the installation ID
cua-driver telemetry reset-id

cua-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>
ArgumentTypeDefaultDescription
<event>stringrequiredFixed telemetry event name.
FlagTypeDefaultDescription
--jsonbooleanfalseEmit 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 --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 <COMMAND>

Examples

# List cursor themes
cua-driver cursor-theme list

cua-driver cursor-theme validate#

Validate a bounded dotLottie source archive.

cua-driver cursor-theme validate [OPTIONS] <source>
ArgumentTypeDefaultDescription
<source>pathrequiredPath to the source .lottie archive.
FlagTypeDefaultDescription
--developmentbooleanfalseAllow the reserved com.example development namespace.

Examples

# Validate a source archive
cua-driver cursor-theme validate my-cursor.lottie

cua-driver cursor-theme build#

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

cua-driver cursor-theme build [OPTIONS] <source>
ArgumentTypeDefaultDescription
<source>pathrequiredPath to the source .lottie archive.
FlagTypeDefaultDescription
--outputpathrequiredOutput .cua-theme path.
--developmentbooleanfalseAllow the reserved com.example development namespace.

Examples

# Compile a theme
cua-driver cursor-theme build my-cursor.lottie --output my-cursor.cua-theme

cua-driver cursor-theme inspect#

Inspect metadata in a compiled .cua-theme artifact.

cua-driver cursor-theme inspect [OPTIONS] <theme>
ArgumentTypeDefaultDescription
<theme>pathrequiredPath to the compiled .cua-theme artifact.
FlagTypeDefaultDescription
--jsonbooleanfalseEmit machine-readable JSON.

Examples

# Print a theme's metadata
cua-driver cursor-theme inspect my-cursor.cua-theme --json

cua-driver cursor-theme preview#

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

cua-driver cursor-theme preview [OPTIONS] <theme>
ArgumentTypeDefaultDescription
<theme>pathrequiredPath to the compiled .cua-theme artifact.
FlagTypeDefaultDescription
--outputpathrequiredPreview output directory.

Examples

# Render still frames
cua-driver cursor-theme preview my-cursor.cua-theme --output preview

cua-driver cursor-theme install#

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

cua-driver cursor-theme install <theme>
ArgumentTypeDefaultDescription
<theme>pathrequiredPath to the compiled .cua-theme artifact.

Examples

# Install a theme
cua-driver cursor-theme install my-cursor.cua-theme

cua-driver cursor-theme list#

List the built-in and installed cursor themes.

cua-driver cursor-theme list [OPTIONS]
FlagTypeDefaultDescription
--jsonbooleanfalseEmit machine-readable JSON.

Examples

# List themes as JSON
cua-driver cursor-theme list --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.

cua-driver cursor-theme uninstall <theme-id>
ArgumentTypeDefaultDescription
<theme-id>stringrequiredInstalled custom theme id.

Examples

# Remove an installed theme
cua-driver cursor-theme uninstall com.example.my-cursor

cua-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 magnetic

cua-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]
FlagTypeDefaultDescription
--sessionstringrequiredPublic label of the session that owns the cursor.
--stylestringsignature_arc, spring_settle, magnetic, comet_swoop, adaptive, or classic.
--timingstringnative, fitts, or fixed.
--effectsstringComma-separated name=on|off|default for trail, glow, magnet, ripple, squish.
--glide-msnumberMove duration in milliseconds for fixed timing (1430 when 0).
--socketpathOverride 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=default

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.

cua-driver check-update [OPTIONS]
FlagTypeDefaultDescription
--jsonbooleanfalseEmit a machine-readable JSON payload.
--no-cachebooleanfalseSkip 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-cache

cua-driver update#

Check for an update and optionally apply it.

The apply path delegates to the canonical platform installer scripts.

cua-driver update [OPTIONS]
FlagTypeDefaultDescription
--applybooleanfalseDownload and install the latest release when one is available.
--jsonbooleanfalseEmit the structured update-state payload.

Examples

# Check and print the install command
cua-driver update
 
# Install the latest release
cua-driver update --apply

cua-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 channel

cua-driver channel status#

Show selected and current release channels.

cua-driver channel status [OPTIONS]
FlagTypeDefaultDescription
--jsonbooleanfalseEmit machine-readable channel state.

Examples

# Show the channels as JSON
cua-driver channel status --json

cua-driver channel set#

Save stable or nightly as the update channel.

cua-driver channel set [OPTIONS] <channel>
ArgumentTypeDefaultDescription
<channel>stringrequiredRelease channel: stable or nightly.
FlagTypeDefaultDescription
--jsonbooleanfalseEmit machine-readable channel state.

Examples

# Follow nightly builds (then run update --apply)
cua-driver channel set nightly

Exit codes#

CodeMeaning
0Success.
1Failure: 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.
2Invalid input: tool arguments that are not valid JSON, an unknown mcp-config client, or an update --apply refused on a local development install.
64Usage 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).