Configuration
Driver configuration, telemetry, cursor themes and cursor motion.
Driver configuration, telemetry, cursor themes and cursor motion.
| Command | Description |
|---|---|
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. |
Every command also accepts the global options.
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.
| 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.
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=default| 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). |