Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(cua-driver): auto-generate CLI and MCP reference docs from source (#1418)

Francesco Bonacci4ee4fa6168cc
diff --git a/.github/workflows/ci-check-docs.yml b/.github/workflows/ci-check-docs.yml
index 9bb726ac06..b7b78a27e6 100644
--- a/.github/workflows/ci-check-docs.yml
+++ b/.github/workflows/ci-check-docs.yml
@@ -3,6 +3,8 @@ name: "CI: Check Docs"
on:
pull_request:
paths:
+ # Cua Driver (Swift)
+ - "libs/cua-driver/Sources/**"
# Lume (Swift)
- "libs/lume/src/**"
# Cua CLI (TypeScript)
@@ -18,6 +20,7 @@ on:
# Cua-Bot
- "libs/cuabot/src/**"
# Documentation files themselves
+ - "docs/content/docs/cua-driver/reference/**"
- "docs/content/docs/cua/reference/**"
- "docs/content/docs/cuabot/reference/**"
# Generator scripts
@@ -56,46 +59,65 @@ jobs:
- name: Determine changed generators
id: changed
run: |
- # Get list of changed files
- CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD)
+ # Diff all commits in this PR against the base branch
+ BASE_SHA="${{ github.event.pull_request.base.sha }}"
+ CHANGED_FILES=$(git diff --name-only "$BASE_SHA" HEAD)
echo "Changed files:"
echo "$CHANGED_FILES"
# Check which generators need to run
GENERATORS=""
- # Lume changes
+ # Source changes
+ if echo "$CHANGED_FILES" | grep -q "^libs/cua-driver/Sources/\|^docs/content/docs/cua-driver/reference/"; then
+ GENERATORS="$GENERATORS cua-driver"
+ fi
if echo "$CHANGED_FILES" | grep -q "^libs/lume/src/"; then
GENERATORS="$GENERATORS lume"
fi
-
- # Cua CLI changes
if echo "$CHANGED_FILES" | grep -q "^libs/typescript/cua-cli/src/"; then
GENERATORS="$GENERATORS cua-cli"
fi
-
- # MCP Server changes
if echo "$CHANGED_FILES" | grep -q "^libs/python/mcp-server/src/"; then
GENERATORS="$GENERATORS mcp-server"
fi
-
- # Python SDK changes (Computer and Agent)
if echo "$CHANGED_FILES" | grep -q "^libs/python/computer/computer/\|^libs/python/agent/agent/"; then
GENERATORS="$GENERATORS python-sdk"
fi
-
- # Cua-Bot changes
if echo "$CHANGED_FILES" | grep -q "^libs/cuabot/src/"; then
GENERATORS="$GENERATORS cuabot"
fi
- # Generator changes should run all
- if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/"; then
+ # Individual generator script changes — only trigger their own generator
+ if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/cua-driver\.ts"; then
+ GENERATORS="$GENERATORS cua-driver"
+ fi
+ if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/lume\.ts"; then
+ GENERATORS="$GENERATORS lume"
+ fi
+ if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/python-sdk\.ts"; then
+ GENERATORS="$GENERATORS python-sdk"
+ fi
+ if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/cuabot\.ts"; then
+ GENERATORS="$GENERATORS cuabot"
+ fi
+
+ # Only runner.ts changes trigger all generators (it's the orchestration layer)
+ # config.json changes only affect whichever generator scripts were also changed
+ if echo "$CHANGED_FILES" | grep -qE "^scripts/docs-generators/runner\.ts$"; then
GENERATORS="all"
fi
+ # Deduplicate
+ GENERATORS=$(echo "$GENERATORS" | tr ' ' '\n' | sort -u | tr '\n' ' ' | xargs)
+
echo "generators=$GENERATORS" >> $GITHUB_OUTPUT
+ - name: Build cua-driver (if needed)
+ if: contains(steps.changed.outputs.generators, 'cua-driver') || steps.changed.outputs.generators == 'all'
+ run: swift build --configuration release
+ working-directory: libs/cua-driver
+
- name: Build Lume (if needed)
if: contains(steps.changed.outputs.generators, 'lume') || steps.changed.outputs.generators == 'all'
run: swift build -c release
diff --git a/docs/content/docs/cua-driver/reference/cli-reference.mdx b/docs/content/docs/cua-driver/reference/cli-reference.mdx
index da22b2e458..7a31501cb6 100644
--- a/docs/content/docs/cua-driver/reference/cli-reference.mdx
+++ b/docs/content/docs/cua-driver/reference/cli-reference.mdx
@@ -3,6 +3,13 @@ title: CLI Reference
description: Command Line Interface reference for Cua Driver
---
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: npx tsx scripts/docs-generators/cua-driver.ts
+ Source: libs/cua-driver/Sources/**/*.swift
+ Version: 0.1.0
+*/}
+
import { Callout } from 'fumadocs-ui/components/callout';
import { VersionHeader } from '@/components/version-selector';
@@ -14,382 +21,349 @@ import { VersionHeader } from '@/components/version-selector';
installCommand="curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash"
/>
-`cua-driver` is a single-binary CLI. Two naming conventions divide its surface:
-
-- **Tool names are `snake_case`** (`launch_app`, `get_window_state`, `click`). Invoke them as `cua-driver <tool> '<JSON-args>'` — the CLI routes through the same `ToolRegistry` the MCP server uses.
-- **Management subcommands are `kebab-case`** (`list-tools`, `describe`, `mcp-config`). These never take JSON args.
-
-Different separators mean no ambiguity. Unknown first-positional args dispatch to the `call` subcommand automatically, so `cua-driver list_apps` is shorthand for `cua-driver call list_apps`.
-
-## Quick start
-
-```bash
-# Start the persistent daemon (required for element_index workflows).
-open -n -g -a CuaDriver --args serve
-
-# Drive an app.
-cua-driver launch_app '{"bundle_id":"com.apple.calculator"}'
-cua-driver get_window_state '{"pid":844,"window_id":10725}'
-cua-driver click '{"pid":844,"window_id":10725,"element_index":14}'
-
-# Stop the daemon.
-cua-driver stop
-```
+macOS Accessibility-driven computer-use agent — MCP stdio server.
## Tool dispatch
### cua-driver call
-Invoke any MCP tool from the shell.
+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.
-```bash
-cua-driver call <tool-name> '<JSON-args>'
-# Shorthand — any unknown first positional arg auto-prefixes `call`:
-cua-driver <tool-name> '<JSON-args>'
-```
+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:**
-- `<tool-name>` — Name of the tool to invoke. Run `cua-driver list-tools` for the full list.
-- `<json-args>` — JSON object matching the tool's `inputSchema`. Omit when stdin is a pipe (JSON is read from stdin) or when the tool takes no 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. |
-**Flags:**
+**Options:**
-- `--raw` — Print the raw `CallTool.Result` JSON (content + structuredContent + isError) instead of unwrapping `structuredContent`.
-- `--screenshot-out-file <path>` — Write the first image content block from the response to `path` (PNG bytes). The default text formatter would drop image content otherwise.
-- `--compact` — Emit minified JSON instead of pretty-printed.
-- `--no-daemon` — Skip the running daemon and run the tool in-process. Element-indexed workflows fail without a daemon because the per-pid cache dies between CLI invocations.
-- `--socket <path>` — Override the daemon Unix socket path.
+| 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. |
-**Examples:**
+**Flags:**
-```bash
-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
-cua-driver get_window_state '{"pid":844,"window_id":1234}' --screenshot-out-file /tmp/shot.png
-```
+| 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 MCP tool exposed by the driver with a one-line summary.
+List every tool exposed by cua-driver with its one-line description.
-```bash
-cua-driver list-tools
-```
+**Options:**
-**Flags:** `--no-daemon`, `--socket <path>`.
+| 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.
-```bash
-cua-driver describe <tool-name>
-```
+**Arguments:**
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `<tool-name>` | String | Yes | Name of the tool to describe. |
-**Flags:** `--compact`, `--no-daemon`, `--socket <path>`.
+**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.
+
### cua-driver serve
-Run cua-driver as a long-running daemon on a Unix domain socket. Required for any workflow that uses `element_index` dispatch: the per-pid element cache lives in-process and survives only between CLI calls routed to the same daemon.
+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.
-```bash
-# Recommended form — routes through LaunchServices for correct TCC context.
-open -n -g -a CuaDriver --args serve
+**Options:**
-# Alternate — auto-relaunches via open when TCC context is wrong.
-cua-driver serve &
-```
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--socket` | String | — | Override the Unix socket path. |
**Flags:**
-- `--socket <path>` — Override the Unix socket path. Default: `~/Library/Caches/cua-driver/cua-driver.sock`.
-- `--no-relaunch` — Stay in the current process instead of relaunching via LaunchServices. Also toggleable via `CUA_DRIVER_NO_RELAUNCH=1`. Use when the calling context already has the right TCC responsibility.
+| 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 daemon to exit gracefully. Polls for the socket file to vanish (up to 2s) as proof of clean shutdown.
+Ask the running cua-driver daemon to exit gracefully.
-```bash
-cua-driver stop
-```
+**Options:**
-**Flags:** `--socket <path>`.
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--socket` | String | — | Override the Unix socket path. |
### cua-driver status
-Report whether a daemon is currently reachable. Probes by sending a trivial `list` request — connecting alone doesn't prove the peer speaks the protocol.
+Report whether a cua-driver daemon is running.
-```bash
-cua-driver status
-# cua-driver daemon is running
-# socket: /Users/you/Library/Caches/cua-driver/cua-driver.sock
-# pid: 12345
-```
+**Options:**
-**Flags:** `--socket <path>`, `--pid-file <path>`.
-
-### cua-driver mcp
-
-Run the stdio MCP server. MCP clients (Claude Code, Cursor, custom SDK clients) spawn this on demand.
-
-```bash
-cua-driver mcp
-```
-
-No flags. Use `cua-driver mcp-config` to generate a paste-able client config snippet.
+| 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.
-**Flags:**
-
-- `--client <name>` (optional): one of `claude`, `codex`, `cursor`, `openclaw`, `opencode`, `hermes`, `pi`. Omit for the generic JSON snippet that any MCP client accepts.
+**Options:**
-**Generic JSON (default):**
+| 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. |
-```bash
-cua-driver mcp-config
-# {
-# "mcpServers": {
-# "cua-driver": {
-# "command": "/Applications/CuaDriver.app/Contents/MacOS/cua-driver",
-# "args": ["mcp"]
-# }
-# }
-# }
-```
+## Trajectory recording
-**Client-specific install commands:**
+### cua-driver recording
-| Client | Output |
-|---|---|
-| `claude` | `claude mcp add --transport stdio cua-driver -- <path> mcp` |
-| `codex` | `codex mcp add cua-driver -- <path> mcp` |
-| `openclaw` | `openclaw mcp set cua-driver '{...}'` (CLI registry) |
-| `cursor` | JSON for `~/.cursor/mcp.json` (no CLI) |
-| `opencode` | JSON snippet for `opencode.json` (`type: "local"`) |
-| `hermes` | YAML for `~/.hermes/config.yaml`, then `/reload-mcp` inside Hermes |
-| `pi` | Points at the CLI path (Pi has no MCP — shell-out to `cua-driver` directly) |
+Control the trajectory recorder on a running cua-driver daemon.
-Pipe to `pbcopy` to put any output on the clipboard, or pass the printed `claude` / `codex` / `openclaw` commands straight to a shell.
+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.
-## Trajectory recording
+#### cua-driver recording start
-### cua-driver recording start
+Enable trajectory recording to the given directory.
-Enable the trajectory recorder. Every subsequent action-tool call (`click`, `right_click`, `scroll`, `type_text`, `press_key`, `hotkey`, `set_value`) writes a numbered turn folder under `<output-dir>`.
+**Arguments:**
-```bash
-cua-driver recording start ~/cua-trajectories/demo1
-```
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `<output-dir>` | String | Yes | Directory to write turn folders into. Expands `~`; created if missing. |
-**Arguments:**
+**Options:**
-- `<output-dir>` — Directory to write turn folders into. Expands `~`; created if missing.
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--socket` | String | — | Override the daemon Unix socket path. |
**Flags:**
-- `--video-experimental` — Also capture the main display to `<output-dir>/recording.mp4` via SCStream (H.264, 30fps, no audio, no cursor). Experimental.
-- `--socket <path>` — Override the daemon socket path.
+| Name | Description |
+| ---- | ----------- |
+| `--video-experimental` | Also capture the main display to `<output-dir>/recording.mp4` via SCStream. Experimental, off by default. |
-Requires a running daemon.
+#### cua-driver recording stop
-### cua-driver recording stop
+Disable trajectory recording.
-Disable recording. Prints the captured turn count and directory.
+**Options:**
-```bash
-cua-driver recording stop
-# Recording disabled (23 turns captured in /Users/you/cua-trajectories/demo1)
-```
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--socket` | String | — | Override the daemon Unix socket path. |
-### cua-driver recording status
+#### cua-driver recording status
Report whether recording is currently enabled.
-```bash
-cua-driver recording status
-# Recording: enabled
-# Output dir: /Users/you/cua-trajectories/demo1
-# Next turn: 24
-```
+**Options:**
-### cua-driver recording render
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--socket` | String | — | Override the daemon Unix socket path. |
-Render a recording directory to a zoomed-on-click MP4. Post-processes the captured `recording.mp4`, `cursor.jsonl`, and `turn-*/action.json` files.
+#### cua-driver recording render
-```bash
-cua-driver recording render ~/cua-rec --output /tmp/out.mp4
-cua-driver recording render ~/cua-rec --output /tmp/baseline.mp4 --no-zoom
-cua-driver recording render ~/cua-rec --output /tmp/out.mp4 --scale 2.5
-```
+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:**
-- `<input-dir>` — Recording directory (contains `session.json`, `recording.mp4`, `cursor.jsonl`, `turn-*/`).
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `<input-dir>` | String | Yes | Recording directory (contains session.json + recording.mp4 + cursor.jsonl + turn-*/). |
-**Flags:**
+**Options:**
-- `--output <path>` — Destination MP4 path. Overwrites any existing file.
-- `--no-zoom` — Skip the zoom curve and re-encode the input as-is. Useful as a baseline check.
-- `--scale <factor>` — Zoom factor applied to each click event. Default `2.0`. Set to `1.0` to disable zoom; `2.0` is 2× magnification.
+| 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:**
-<Callout type="info">
- `recording render` runs in the CLI process directly — it does not require a running daemon.
-</Callout>
+| 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 settings at `~/Library/Application Support/Cua Driver/config.json`.
+Read and write persistent cua-driver settings.
-```bash
-cua-driver config # print full config
-cua-driver config get <key>
-cua-driver config set <key> <value>
-cua-driver config reset # overwrite with defaults
-```
+Persistent config lives at
+`~/Library/Application Support/<app-name>/config.json` and
+survives daemon restarts.
-**Supported keys:**
+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
-- `capture_mode` — `som` | `ax` | `vision`. Default `som`.
-- `max_image_dimension` — integer. PNG long-side cap. Default 1568.
-- `agent_cursor.enabled` — boolean.
-- `agent_cursor.motion.start_handle` — number in [0, 1].
-- `agent_cursor.motion.end_handle` — number in [0, 1].
-- `agent_cursor.motion.arc_size` — number (fraction of path length).
-- `agent_cursor.motion.arc_flow` — number in [-1, 1].
-- `agent_cursor.motion.spring` — number in [0.3, 1.0].
+#### cua-driver config show
-**Flags on `set`:** `--socket <path>`.
+Print the full current config as JSON.
-Writes route through the daemon when one's reachable so live state (e.g. `AgentCursor.shared`) picks up the change without a restart.
+#### cua-driver config get
-### cua-driver config telemetry
+Print a single config value by key.
-Manage anonymous telemetry.
+**Arguments:**
-```bash
-cua-driver config telemetry status
-cua-driver config telemetry enable
-cua-driver config telemetry disable
-```
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `<key>` | String | Yes | Config key to read (e.g. `schema_version`, `agent_cursor.enabled`). |
-Environment override: `CUA_DRIVER_TELEMETRY_ENABLED=0|1`.
+#### cua-driver config set
-### cua-driver config updates
+Write a single config value by dotted snake_case key.
-Manage automatic updates.
+**Arguments:**
-```bash
-cua-driver config updates status
-cua-driver config updates enable
-cua-driver config updates disable
-```
+| 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. |
-Environment override: `CUA_DRIVER_AUTO_UPDATE_ENABLED=0|1`.
+**Options:**
-## Diagnostics
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--socket` | String | — | Override the daemon Unix socket path. |
-### cua-driver diagnose
+#### cua-driver config reset
-Print a paste-able state report for support. Covers: running-process identity (path, bundle id, pid, cdhash), TCC probe results, install layout (`/Applications/CuaDriver.app` + codesign info, `~/.local/bin/cua-driver` symlink resolution), TCC database rows for `com.trycua.driver`, and config + state paths.
+Overwrite the config file with defaults.
-```bash
-cua-driver diagnose
-```
+#### cua-driver config telemetry
-Use this when filing an issue about permissions or install problems.
+Manage anonymous telemetry settings.
-### cua-driver update
+##### cua-driver config telemetry status
-Check GitHub for a newer cua-driver release and optionally apply it.
+Show whether anonymous telemetry is enabled.
-```bash
-cua-driver update # report what's available
-cua-driver update --apply # download and install the latest release
-```
+##### cua-driver config telemetry enable
-**Flags:** `--apply` — download and apply the update without prompting. Without this flag, `update` only reports the available version and the install command.
+Enable anonymous telemetry.
-### cua-driver doctor
+##### cua-driver config telemetry disable
-Clean up stale install bits left from older cua-driver versions (`≤ v0.0.5`) — the legacy weekly LaunchAgent and the `/usr/local/bin/cua-driver-update` companion script that v0.0.6 dropped.
+Disable anonymous telemetry.
-```bash
-cua-driver doctor
-```
+#### cua-driver config updates
-Idempotent and safe to re-run. Prints `Nothing to clean — install is up to date.` when there's nothing to do. The `~/Library/LaunchAgents/...` plist is removed automatically; the `/usr/local/bin/cua-driver-update` script (root-owned) is surfaced as a `sudo rm -f` command for the user to run manually.
+Manage automatic update settings.
-## Global options
+##### cua-driver config updates status
-Available on all commands:
+Show whether automatic updates are enabled.
-- `--help` — Show help information.
-- `--version` — Show version number.
+##### cua-driver config updates enable
-## Tool inventory
+Enable automatic updates.
-The following MCP tools are callable via `cua-driver <tool>`. For input schemas and response shapes, see the [MCP tools reference](/cua-driver/reference/mcp-tools).
+##### cua-driver config updates disable
-**Discovery and permissions**
+Disable automatic updates.
-- `list_apps` — running + installed apps with pid / bundle id / active state.
-- `list_windows` — every layer-0 top-level window (including off-screen).
-- `check_permissions` — Accessibility + Screen Recording TCC status.
-- `get_screen_size` — main display size in points + scale factor.
-- `get_cursor_position` — current mouse cursor position.
+## Diagnostics
-**App lifecycle**
+### cua-driver update
-- `launch_app` — launch hidden; returns pid + windows array.
+Check for a newer cua-driver release and apply it.
-**Snapshot**
+**Flags:**
-- `get_window_state` — per-window AX tree + screenshot. Populates the element_index cache.
-- `screenshot` — raw ScreenCaptureKit capture. Full display or single window.
-- `zoom` — native-resolution crop of a previously captured window region.
+| Name | Description |
+| ---- | ----------- |
+| `--apply` | Download and apply the update without prompting. |
-**Mouse**
+### cua-driver diagnose
-- `click` — left-click by `element_index` or `(x, y)`.
-- `double_click` — double-click by `element_index` (AXOpen) or `(x, y)`.
-- `right_click` — right-click by `element_index` (AXShowMenu) or `(x, y)`.
-- `drag` — press-drag-release between two pixel endpoints (marquee, drag-and-drop, slider scrub, resize handles).
-- `move_cursor` — warp the real cursor to `(x, y)`.
+Print a paste-able bundle-path / cdhash / TCC-status report for support.
-**Keyboard**
+### cua-driver doctor
-- `type_text` — insert text via `AXSelectedText` with automatic CGEvent fallback for Chromium/Electron inputs. Pid-scoped.
-- `press_key` — single key press. Pid-scoped.
-- `hotkey` — modifier combo (e.g. `["cmd","c"]`). Pid-scoped.
+Clean up stale install bits left from older cua-driver versions.
-**Element attributes**
+## Other commands
-- `set_value` — write an element's `AXValue` directly. For sliders, steppers, and text fields.
-- `scroll` — synthesize PageUp/PageDown/arrow keystrokes against the target pid.
+### cua-driver dump-docs
-**Agent cursor overlay**
+Output CLI and MCP tool documentation as JSON for tooling and integrations.
-- `set_agent_cursor_enabled` — toggle the visual overlay.
-- `set_agent_cursor_motion` — tune the Bezier-arc + spring motion knobs.
-- `set_agent_cursor_style` — customize the cursor's visual appearance (gradient colors, bloom color, image path).
-- `get_agent_cursor_state` — read the current overlay configuration.
+**Options:**
-**Config**
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--type` | String | all | Documentation type: cli, mcp, or all |
-- `get_config` — report persistent config as JSON.
-- `set_config` — write a single dotted-path config key.
+**Flags:**
+
+| Name | Description |
+| ---- | ----------- |
+| `--pretty` | Pretty-print JSON output |
-**Recording**
+## Global options
-- `set_recording` — toggle the trajectory recorder.
-- `get_recording_state` — report recorder state.
-- `replay_trajectory` — re-invoke every turn's tool call in lexical order.
+Available on all commands:
+
+- `--help` — Show help information.
+- `--version` — Show version number.
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools.mdx b/docs/content/docs/cua-driver/reference/mcp-tools.mdx
index e00f452577..b16542adbd 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools.mdx
@@ -3,9 +3,16 @@ title: MCP Tools
description: Reference for every MCP tool cua-driver exposes
---
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: npx tsx scripts/docs-generators/cua-driver.ts
+ Source: libs/cua-driver/Sources/**/*.swift
+ Version: 0.1.0
+*/}
+
import { Callout } from 'fumadocs-ui/components/callout';
-`cua-driver` exposes 28 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver <name> '<JSON-args>'`.
+`cua-driver` exposes 29 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver <name> '<JSON-args>'`.
Tool names are `snake_case`. Responses are MCP `CallTool.Result` envelopes: a text content block prefixed with a `✅` summary (or the error reason on failure), plus optional image or structured-content blocks on tools that produce them. See the [CLI reference](/cua-driver/reference/cli-reference) for CLI-specific flags like `--raw` and `--screenshot-out-file`.
@@ -13,193 +20,507 @@ Tool names are `snake_case`. Responses are MCP `CallTool.Result` envelopes: a te
Tool names here match the CLI form exactly. `cua-driver list_apps` and the MCP `list_apps` tool run the same code path.
</Callout>
-## Discovery
+### check_permissions
-### list_apps
+Report TCC permission status for Accessibility and Screen Recording.
+By default also raises the system permission dialogs for any missing
+grants — Apple's request APIs are no-ops when the grant is already
+active, so this is safe to call repeatedly. Pass {"prompt": false}
+for a purely read-only status check.
-List macOS apps, both running and installed-but-not-running, with pid / bundle id / active state.
+**Arguments:**
-**Arguments:** none.
+- `prompt` (boolean, optional): Raise the system permission prompts for missing grants. Default true.
-```json
-{}
-```
-
-### list_windows
+### click
-List every layer-0 top-level window currently known to WindowServer, including off-screen ones (hidden-launched, minimized, on another Space).
+Left-click against a target pid. Two addressing modes:
+
+- `element_index` + `window_id` (from the last
+ `get_window_state` snapshot of that window) —
+ performs an AX action on the cached element. Default
+ `action` is `press` (left-click). Other values:
+ `show_menu` (right-click equivalent), `pick` (open a
+ menu-bar item's submenu), `confirm` (return on a
+ default button), `cancel` (escape on a dismiss
+ button), `open` (open a file/folder in a browser).
+ Pure AX RPC, works on backgrounded / hidden windows,
+ no cursor move or focus steal. Requires a prior
+ `get_window_state(pid, window_id)` in this turn; the
+ element_index cache is scoped per (pid, window_id) so
+ indices from one window do not resolve against another.
+
+- `x`, `y` (window-local screenshot pixels, top-left
+ origin of the PNG returned by `get_window_state`) —
+ synthesizes mouse events via CGEvent / SkyLight and
+ delivers them to the pid. AX is never consulted on
+ this path. The driver converts image-pixel →
+ screen-point internally using the target's window
+ origin and backing scale. `count: 2` posts two
+ down/up pairs ~80ms apart for a double-click.
+ `modifier` holds cmd/shift/option/ctrl during the
+ click (e.g. ["cmd"] for cmd-click).
+
+Exactly one of `element_index` or (`x` AND `y`) must be
+provided. `pid` is required in both modes. `window_id`
+is required when `element_index` is used (scopes the
+cache lookup). `action` is only valid with
+`element_index`; `count` and `modifier` are ignored in
+the AX path.
**Arguments:**
-- `pid` (integer, optional): Pid filter. When set, only this pid's windows are returned.
-- `on_screen_only` (boolean, optional): When true, drop windows that aren't currently on the user's Space. Default false.
+- `action` (string, optional): AX action name (element_index path only). Default: press.
+- `count` (integer, optional): Click count — 1 (single), 2 (double), 3 (triple). Pixel path only. Default: 1.
+- `debug_image_out` (string, optional): Optional absolute path. When set on a pixel-addressed click (x, y present), the tool captures a fresh screenshot of the target window at the current max_image_dimension, draws a red crosshair at the received (x, y), and writes the PNG to this path. Use this to verify the tool received the coordinate you intended — if you drew your own blue crosshair on the PNG from get_window_state and saved it separately, the two crosshairs must land on the same pixel. Mismatch surfaces a coord-space bug. Pixel path only; requires window_id; incompatible with from_zoom.
+- `element_index` (integer, optional): Element index from the last get_window_state for the same (pid, window_id). Routes through the AX action path. Requires window_id.
+- `from_zoom` (boolean, optional): When true, x and y are pixel coordinates in the last `zoom` image for this pid. The driver automatically maps them back to the correct window coordinates. Use this after calling `zoom` to click on something you saw in the zoomed image.
+- `modifier` (array of string, optional): Modifier keys held during the click: cmd/shift/option/ctrl. Pixel path only.
+- `pid` (integer, required): Target process ID.
+- `window_id` (integer, optional): CGWindowID for the window whose get_window_state produced the element_index. Required when element_index is used; ignored in the pixel path.
+- `x` (number, optional): X in window-local screenshot pixels — same space as the PNG get_window_state returns. Top-left origin of the target's window. Must be provided together with y.
+- `y` (number, optional): Y in window-local screenshot pixels — same space as the PNG get_window_state returns. Top-left origin of the target's window. Must be provided together with x.
```json
-{"pid": 844, "on_screen_only": true}
+{"pid":844}
```
-### get_screen_size
+### double_click
-Return the main display's logical size in points plus the backing scale factor. Retina displays report `2.0`.
+Double-click against a target pid. Two addressing modes:
+
+- `element_index` + `window_id` (from the last
+ `get_window_state` snapshot of that window) —
+ performs `AXOpen` when the element advertises it
+ (Finder items, list rows, openable cells); otherwise
+ falls back to a stamped pixel double-click at the
+ element's on-screen center. Pure AX RPC in the
+ AXOpen branch; pixel recipe when no AX open action
+ exists. Requires a prior
+ `get_window_state(pid, window_id)` in this turn.
+
+- `x`, `y` (window-local screenshot pixels, top-left
+ origin of the PNG returned by `get_window_state`) —
+ synthesizes a stamped double-click (two down/up
+ pairs with clickState 1→2) and delivers to the pid.
+ The primer-gated auth-signed recipe lands on
+ backgrounded Chromium web content (dblclick events
+ that trigger YouTube fullscreen toggle, Finder
+ open-on-double-click, etc.). `modifier` holds
+ cmd/shift/option/ctrl during the gesture.
+
+Exactly one of `element_index` or (`x` AND `y`) must be
+provided. `pid` is required in both modes. `window_id`
+is required when `element_index` is used. `modifier`
+only takes effect in the pixel path (AXOpen doesn't
+propagate modifier keys).
-**Arguments:** none.
+**Arguments:**
+
+- `element_index` (integer, optional): Element index from the last get_window_state for the same (pid, window_id). Routes through AXOpen when advertised, else pixel double-click at the element's center. Requires window_id.
+- `modifier` (array of string, optional): Modifier keys held during the double-click: cmd/shift/option/ctrl. Pixel path only.
+- `pid` (integer, required): Target process ID.
+- `window_id` (integer, optional): CGWindowID for the window whose get_window_state produced the element_index. Required when element_index is used; ignored in the pixel path.
+- `x` (number, optional): X in window-local screenshot pixels — same space as the PNG get_window_state returns. Top-left origin of the target's window. Must be provided together with y.
+- `y` (number, optional): Y in window-local screenshot pixels — same space as the PNG get_window_state returns. Top-left origin of the target's window. Must be provided together with x.
```json
-{}
+{"pid":844}
```
-### get_cursor_position
+### drag
-Return the current mouse cursor position in screen points (top-left origin).
+Press-drag-release gesture from (`from_x`, `from_y`) to
+(`to_x`, `to_y`) in window-local screenshot pixels —
+the same space the PNG `get_window_state` returns.
+Top-left origin of the target's window.
+
+Use this for: marquee/lasso selection, drag-and-drop
+between source and destination, resizing via a handle,
+scrubbing a slider, repositioning a panel. macOS AX
+has no semantic drag action, so drag is pixel-only —
+there is no element-indexed mode. Address an element
+with `get_window_state`, read its `bounds`, and pass
+the pixel coordinates you want.
+
+`duration_ms` (default 500) is the wall-clock budget
+for the path between mouse-down and mouse-up; `steps`
+(default 20) is the number of intermediate `mouseDragged`
+events linearly interpolated along the path. Increase
+both for slower, more "human" drags; decrease for snap
+gestures. `modifier` keys (cmd/shift/option/ctrl) are
+held across the entire gesture — option-drag duplicates,
+shift-drag constrains the axis on most surfaces.
+
+Frontmost target: posts via `.cghidEventTap`. The real
+cursor visibly traces the drag path — unavoidable for
+AppKit-style drag sources, which accept only HID-origin
+events.
+
+Backgrounded target: posts via the auth-signed pid-routed
+path. Cursor-neutral, but some surfaces (OpenGL canvases,
+Blender, Unity) filter pid-routed dragged events at the
+event-source level — those targets must be frontmost.
+
+When `from_zoom` is true, both endpoints are pixel
+coordinates in the last `zoom` image for this pid; the
+driver maps them back to window coordinates before
+dispatching.
-**Arguments:** none.
+**Arguments:**
+
+- `button` (string, optional): Mouse button used for the drag. Default: left.
+- `duration_ms` (integer, optional): Wall-clock duration of the drag path between mouseDown and mouseUp. Default: 500.
+- `from_x` (number, required): Drag-start X in window-local screenshot pixels. Top-left origin.
+- `from_y` (number, required): Drag-start Y in window-local screenshot pixels. Top-left origin.
+- `from_zoom` (boolean, optional): When true, from_x/from_y/to_x/to_y are pixel coordinates in the last `zoom` image for this pid. The driver maps them back to window coordinates before dispatching.
+- `modifier` (array of string, optional): Modifier keys held across the entire gesture: cmd/shift/option/ctrl.
+- `pid` (integer, required): Target process ID.
+- `steps` (integer, optional): Number of intermediate mouseDragged events linearly interpolated along the path. Default: 20.
+- `to_x` (number, required): Drag-end X in window-local screenshot pixels.
+- `to_y` (number, required): Drag-end Y in window-local screenshot pixels.
+- `window_id` (integer, optional): CGWindowID for the window the pixel coordinates were measured against. Optional — when omitted the driver picks the frontmost window of `pid`. Pass when the target has multiple windows and you measured against a specific one.
```json
-{}
+{"from_x":100,"from_y":200,"pid":844,"to_x":100,"to_y":200}
```
-### screenshot
+### get_agent_cursor_state
-Raw ScreenCaptureKit capture. Full main display, or a single window when `window_id` is set. Returns an image content block plus a text summary listing on-screen windows.
+Report the current agent-cursor configuration: enabled flag,
+motion knobs (startHandle, endHandle, arcSize, arcFlow,
+spring), glide duration, post-click dwell, and idle-hide
+delay. Durations come back in milliseconds to match the
+setter's units. Pure read-only — no side effects.
-**Arguments:**
+**Arguments:** none.
-- `format` (string, optional): `"png"` or `"jpeg"`. Default `"png"`.
-- `quality` (integer, optional): JPEG quality 1-95; ignored for png.
-- `window_id` (integer, optional): CGWindowID / `kCGWindowNumber` to capture just that window.
+### get_config
-```json
-{"format": "jpeg", "quality": 80, "window_id": 10725}
-```
+Report the current persistent driver config. Config lives
+at `~/Library/Application Support/<app-name>/config.json`
+and survives daemon restarts, unlike session-scoped state
+(recording).
+
+Pure read-only. Returns defaults when the file doesn't
+exist or fails to decode — same fallback the daemon uses
+at startup. Sibling to `set_config` / `cua-driver config`.
+
+Current schema:
+
+ {
+ "schema_version": 1,
+ "capture_mode": "vision" | "ax" | "som",
+ "agent_cursor": {
+ "enabled": true,
+ "motion": {
+ "start_handle": 0.3, "end_handle": 0.3,
+ "arc_size": 0.25, "arc_flow": 0.0,
+ "spring": 0.72
+ }
+ }
+ }
-### get_window_state
-
-Snapshot a single window: AX element tree plus a screenshot. Populates the per-pid, per-window `element_index` cache that mouse and keyboard tools consume.
+**Arguments:** none.
-**Arguments:**
+### get_cursor_position
-- `pid` (integer, required): Process ID from `list_apps`.
-- `window_id` (integer, required): CGWindowID of the target window. Must belong to `pid`. Enumerate via `list_windows` or read from `launch_app`'s `windows` array.
-- `query` (string, optional): Case-insensitive substring. When set, `tree_markdown` only contains matching lines plus their ancestor chain; element indices and `element_count` are unchanged.
-- `screenshot_out_file` (string, optional): Absolute path to write the screenshot to. When set, the screenshot bytes are written to this file, the MCP image content block is omitted, and `screenshot_file_path` is returned instead. Useful for agents that cannot consume inline base64 without saturating their context window.
+Return the current mouse cursor position in screen points (origin top-left).
-```json
-{"pid": 844, "window_id": 10725, "query": "save"}
-```
+**Arguments:** none.
-<Callout type="info">
- Response shape varies by `capture_mode` (`som` / `ax` / `vision`). Default is `som`. See the [CLI reference](/cua-driver/reference/cli-reference) for the full matrix.
-</Callout>
+### get_recording_state
-## App lifecycle
+Report the current trajectory recorder state: whether
+recording is enabled, the output directory (when
+enabled), and the 1-based counter for the next turn
+folder that will be written. Counter increments on every
+recorded action tool call and resets to 1 each time
+recording is (re-)enabled.
-### launch_app
+Pure read-only. Typical use: `cua-driver recording
+status` surfaces these fields for human consumption;
+programmatic callers use it to confirm recording is
+armed before kicking off a session.
-Launch an app hidden (no focus steal) and return its pid plus the initial `windows` array. Either `bundle_id` or `name` must be provided.
+**Arguments:** none.
-**Arguments:**
+### get_screen_size
-- `bundle_id` (string, optional): App bundle identifier, e.g. `com.apple.calculator`.
-- `name` (string, optional): App display name. Used only when `bundle_id` is absent.
-- `urls` (array of string, optional): `file://` / `http(s)://` URLs (or plain paths with `~` expansion) handed to the launched app via `application(_:open:)`. For Finder, a folder URL opens a backgrounded window rooted there. Apps that don't implement `application(_:open:)` launch normally and ignore these.
-- `creates_new_application_instance` (boolean, optional): When true, force-launches a separate process even if the app is already running. Useful for isolated browser sessions. Default false.
-- `additional_arguments` (array of string, optional): Extra command-line arguments passed to the launched process, e.g. `["--user-data-dir=/tmp/session-a"]` for an isolated Chrome profile.
+Return the logical size of the main display in points plus its backing scale
+factor. Agents click in points; Retina displays have scale_factor 2.0.
+Requires no TCC permissions.
-```json
-{"bundle_id": "com.google.Chrome", "urls": ["https://example.com"], "creates_new_application_instance": true, "additional_arguments": ["--user-data-dir=/tmp/cua-session"]}
-```
+**Arguments:** none.
-### check_permissions
+### get_window_state
-Report TCC permission status for Accessibility and Screen Recording. By default also raises the system permission dialogs for any missing grants — Apple's request APIs no-op when the grant is already active, so the call is safe to repeat.
+Walk a running app's AX tree and return a Markdown rendering of its
+UI, tagging every actionable element with [element_index N]. Pass
+those indices to `click`, `type_text_in`, `scroll_in`, etc. — those
+tools resolve the index to the cached AXUIElement on the server.
+
+INVARIANT: call `get_window_state` once per turn per (pid, window_id)
+before any element-indexed action against that window. The index
+map is replaced by the next snapshot of the same (pid, window_id).
+
+The AX tree walked is the pid's tree, but the screenshot and window
+bounds reported come from the specified `window_id`. This is the
+source of truth for which window the caller intends to reason about
+— the driver never picks a window implicitly. Use `list_windows` to
+enumerate candidates, or read `launch_app`'s `windows` field for
+freshly-launched apps.
+
+`window_id` MUST belong to `pid` and MUST be on the user's current
+Space; the call returns `isError: true` otherwise. The driver does
+not auto-fall-back to a different window — window selection is the
+caller's responsibility.
+
+The screenshot of the specified window is delivered as a native MCP
+image content block (not a JSON text field), so clients receive it
+as a proper image rather than raw base64 text.
+
+Set `query` to a case-insensitive substring to filter
+`tree_markdown` down to matching lines plus their ancestor
+chain (so the structural context above each match stays
+visible). The element_index values and `element_count` are
+unchanged — the filter only trims the rendered Markdown, so
+`click({pid, window_id, element_index: N})` still resolves
+against the full cached tree. When nothing matches,
+`tree_markdown` is an empty string; the caller can retry
+without the filter.
+
+Response shape is controlled by the persistent
+`capture_mode` config setting (default `som`). Each
+mode skips the half of the work it doesn't need — not
+just the half of the response. Note that `vision` names
+the capture MODE; the separate `screenshot` tool (which
+captures a raw PNG without walking AX) is unrelated and
+keeps its name:
+ - `som` — walks AX tree AND captures screenshot
+ (default). Element-indexed clicks work
+ out of the box; screenshot is there for
+ disambiguation.
+ - `vision` — captures the window PNG; AX tree walk
+ is skipped entirely (no Accessibility
+ hit, no element_index cache update).
+ `tree_markdown`, `element_count`, and
+ `turn_id` omitted. Element-indexed
+ clicks will fail until a non-`vision`
+ snapshot runs — pair with pixel-addressed
+ `click({pid, x, y})`. Previously named
+ `screenshot`; the raw string
+ `"screenshot"` still decodes to `vision`
+ as a deprecated alias.
+ - `ax` — walks AX tree; screen-capture call is
+ skipped entirely (no Screen Recording
+ hit). `screenshot_*` fields omitted.
+Change with `cua-driver config set capture_mode <mode>` or
+the `set_config` tool.
+
+Requires Accessibility and Screen Recording permissions.
**Arguments:**
-- `prompt` (boolean, optional): Raise the system permission prompts for missing grants. Default `true`. Pass `false` for a purely read-only status check.
+- `javascript` (string, optional): Optional JavaScript to execute in the browser tab and return alongside the AX snapshot — one round-trip instead of two. Only works for Chromium-family browsers (Chrome, Brave, Edge) and Safari; requires 'Allow JavaScript from Apple Events' to be enabled first (see WEB_APPS.md). The result is appended to the response as a `## JavaScript result` section. Use for read-only queries (document.title, innerText, querySelectorAll, etc.). For mutations or side effects use the `page` tool instead.
+- `pid` (integer, required): Process ID from `list_apps`.
+- `query` (string, optional): Optional case-insensitive substring. When set, `tree_markdown` only contains lines that match plus their ancestor chain; element indices and `element_count` are unchanged.
+- `screenshot_out_file` (string, optional): Optional absolute path to write the screenshot to (e.g. "/tmp/shot.jpg"). When set, the screenshot bytes are written to this file and the MCP image content block is omitted from the response — `screenshot_file_path` is returned instead of `screenshot_png_b64`. Useful for CLI callers and agents that cannot consume inline base64 without saturating their context window (e.g. OpenCode with a local Ollama model). The directory must already exist; the file is created or overwritten.
+- `window_id` (integer, required): CGWindowID of the target window. Must belong to `pid` and be on the user's current Space. Enumerate via `list_windows` or read from `launch_app`'s `windows` array.
```json
-{"prompt": false}
+{"pid":844,"window_id":10725}
```
-## Mouse
-
-All mouse tools accept either the `element_index` path (preferred; works on backgrounded windows) or a pixel `(x, y)` path. Pixel coordinates are in window-local screenshot pixels, the same space as the PNG `get_window_state` returns.
+### hotkey
-### click
+Press a combination of keys simultaneously — e.g.
+`["cmd", "c"]` for Copy, `["cmd", "shift", "4"]` for
+screenshot selection. The combo is posted directly to
+the target pid's event queue via `CGEvent.postToPid`;
+the target does NOT need to be frontmost.
-Left-click by element or pixel.
+Recognized modifiers: cmd/command, shift, option/alt,
+ctrl/control, fn. Non-modifier keys use the same
+vocabulary as `press_key` (return, tab, escape,
+up/down/left/right, space, delete, home, end, pageup,
+pagedown, f1-f12, letters, digits). Order: modifiers
+first, one non-modifier last.
**Arguments:**
+- `keys` (array of string, required): Modifier(s) and one non-modifier key, e.g. ["cmd", "c"].
- `pid` (integer, required): Target process ID.
-- `element_index` (integer, optional): Element index from the last `get_window_state` for the same `(pid, window_id)`. Routes through the AX action path. Requires `window_id`.
-- `window_id` (integer, optional): CGWindowID for the window whose `get_window_state` produced `element_index`. Required in the element path; ignored in the pixel path.
-- `x`, `y` (number, optional): Pixel coordinates (top-left origin). Must be provided together.
-- `action` (string, optional): AX action: `press` | `show_menu` | `pick` | `confirm` | `cancel` | `open`. Default `press`. Element path only.
-- `modifier` (array of string, optional): Modifiers held during the click: `cmd` / `shift` / `option` / `ctrl`. Pixel path only.
-- `count` (integer, optional): Click count 1-3 (single, double, triple). Default 1. Pixel path only.
-- `from_zoom` (boolean, optional): When true, `x`, `y` are pixel coordinates in the last `zoom` image for this pid; the driver maps them back to window coordinates automatically.
-- `debug_image_out` (string, optional): Absolute path. On a pixel-addressed click, the tool captures the window at current `max_image_dimension`, draws a red crosshair at the received `(x, y)`, and writes the PNG here. Use to verify coordinate-space correctness. Incompatible with `from_zoom`.
```json
-{"pid": 844, "window_id": 10725, "element_index": 14}
+{"keys":["cmd","c"],"pid":844}
```
-### double_click
+### launch_app
-Double-click by element (routes through `AXOpen` when advertised, else pixel double-click at the element's center) or by pixel.
+Launch a macOS app hidden — the driver never brings the
+target to the foreground, and the target's window is not
+drawn on screen. This tool is strictly a background-launch
+primitive; if a human operator wants to switch the
+foreground app, they should do so through normal macOS UI
+(Dock, Cmd-Tab, Spotlight), not through this driver.
+
+Provide either `bundle_id` (preferred — unambiguous, e.g.
+`com.apple.calculator`) or `name` (e.g. "Calculator", resolved
+against /Applications and /System/Applications). If both are
+given, bundle_id wins.
+
+Launches hidden — the app runs with its window initialized
+for automation (so the AX tree is populated and
+`click({pid, element_index})` works end-to-end), but no
+window is drawn on screen. To bring the window on-screen,
+use `NSRunningApplication.unhide()` from your own code, or
+have the user open the app (Dock click, Cmd-Tab, Spotlight).
+
+Some apps (Calculator and many Electron apps) call
+`NSApp.activate(ignoringOtherApps:)` in their own
+`applicationDidFinishLaunching`, overriding
+`NSWorkspace.OpenConfiguration.activates = false`. A layer-3
+focus-steal preventer arms a short
+`NSWorkspace.didActivateApplicationNotification` watcher
+around the launch and re-activates the previously-frontmost
+app if the target self-activates. If suppression fails the
+returned summary includes a "self-activation not suppressed"
+warning. With `hides = true`, the target is also hidden
+back immediately by LaunchServices, so even a missed
+layer-3 demotion doesn't leave a visible window.
+
+Optional `urls` are handed to the app through its
+`application(_:open:)` AppKit delegate. For Finder, passing
+a folder URL opens a backgrounded Finder window rooted at
+that folder — no activation, no visible window. Works
+with any app that implements `application(_:open:)`; apps
+that ignore the delegate simply launch without side effects.
+
+Optional `electron_debugging_port` launches an Electron app
+with `--remote-debugging-port=<N>`, activating its Chrome
+DevTools Protocol (CDP) on that port. This gives the `page`
+tool full renderer/DOM access (`document`, `window`,
+`fetch`, etc.) via page targets rather than the restricted
+Node main-process context exposed by SIGUSR1. Use port 9222
+unless you're running multiple Electron apps simultaneously.
+Has no effect on non-Electron apps.
+
+Optional `webkit_inspector_port` launches a Tauri/WKWebView
+app with `WEBKIT_INSPECTOR_SERVER=127.0.0.1:<N>`, activating
+WebKit's remote inspector. The `page` tool will use this to
+execute JavaScript in the WKWebView renderer. Use port 9226
+(reserved WebKit range: 9226–9228). Requires
+`developerExtrasEnabled = true` in the app's WKWebView config
+(default in Tauri debug builds; production builds may disable
+it). Has no effect on non-WKWebView apps.
+
+Use this instead of shelling out to `open -a` — the shell form
+always activates the target, requires an extra permission
+prompt for Bash, and doesn't even try to respect
+background-launch intent.
+
+Returns the launched app's pid, bundle_id, name, active
+flag, AND a `windows` array — same per-window shape as
+`list_windows` returns (window_id, title, bounds,
+z_index, is_on_screen, on_current_space, space_ids).
+That lets callers skip an extra `list_windows` round-trip
+before `get_window_state(pid, window_id)` in the common
+case. When the launch settles but no window has
+materialized yet (transient; rare), `windows` comes back
+empty — call `list_windows(pid)` explicitly a moment
+later to resolve a target.
**Arguments:**
-- `pid` (integer, required): Target process ID.
-- `element_index` (integer, optional): Requires `window_id`.
-- `window_id` (integer, optional): Required when `element_index` is used.
-- `x`, `y` (number, optional): Pixel coordinates (top-left origin). Provided together.
-- `modifier` (array of string, optional): `cmd` / `shift` / `option` / `ctrl`. Pixel path only.
+- `additional_arguments` (array of string, optional): Extra command-line arguments passed to the launched process. Passed directly as argv entries — no shell expansion. Example: ["--user-data-dir=/tmp/cua-session", "--no-first-run"] for an isolated Chrome session.
+- `bundle_id` (string, optional): App bundle identifier, e.g. com.apple.calculator.
+- `creates_new_application_instance` (boolean, optional): Force a brand-new process even if the app is already running. Useful for isolated browser sessions: pass creates_new_application_instance=true together with additional_arguments=["--user-data-dir=/tmp/session-a", "--no-first-run", "--no-default-browser-check"] to launch a sandboxed Chrome that cannot see the user's real profile, cookies, or extensions. Each session gets its own pid and window identity and can be controlled independently.
+- `electron_debugging_port` (integer, optional): Launch an Electron app with --remote-debugging-port=<N> so the `page` tool gets full renderer/DOM access. Use 9222 unless running multiple Electron apps. Ignored for non-Electron apps.
+- `name` (string, optional): App display name. Used only when bundle_id is absent.
+- `urls` (array of string, optional): Optional file:// or http(s):// URLs (or plain paths with ~ expansion) to hand to the launched app via application(_:open:). For Finder, pass a folder URL or path to open a backgrounded Finder window rooted at that folder — no activation. Apps that don't implement application(_:open:) launch normally and ignore these.
+- `webkit_inspector_port` (integer, optional): Launch a Tauri/WKWebView app with WEBKIT_INSPECTOR_SERVER=127.0.0.1:<N> so the `page` tool can reach its WebKit inspector. Use 9226 (reserved WebKit range: 9226–9228, distinct from Electron's 9222–9225). Requires developerExtrasEnabled=true in the WKWebView config (default in Tauri debug builds).
-```json
-{"pid": 844, "x": 320, "y": 180}
-```
+### list_apps
-### right_click
+List macOS apps — both currently running and installed-but-not-running —
+with per-app state flags:
-Right-click by element (routes through `AXShowMenu`) or by pixel.
+- running: is a process for this app live? (pid is 0 when false)
+- active: is it the system-frontmost app? (implies running)
-**Arguments:**
+Only apps with NSApplicationActivationPolicyRegular are included —
+background helpers and system UI agents are filtered out. Installed
+apps come from scanning /Applications, /Applications/Utilities,
+~/Applications, /System/Applications, and /System/Applications/Utilities.
-- `pid` (integer, required): Target process ID.
-- `element_index` (integer, optional): Requires `window_id`.
-- `window_id` (integer, optional): Required when `element_index` is used.
-- `x`, `y` (number, optional): Pixel coordinates (top-left origin). Provided together.
-- `modifier` (array of string, optional): `cmd` / `shift` / `option` / `ctrl`. Pixel path only.
+Use this for "is X installed?" as well as "is X running?". For
+per-window state — on-screen, on-current-Space, minimized,
+window titles — call list_windows instead. For just opening an
+app — running or not — call launch_app({bundle_id: ...}) directly;
+list_apps is not a prerequisite.
-```json
-{"pid": 844, "window_id": 10725, "element_index": 7}
-```
+**Arguments:** none.
-### drag
+### list_windows
-Press-drag-release gesture between two pixel endpoints. macOS AX has no semantic drag action, so this is pixel-only — there is no element-indexed mode. Use it for marquee/lasso selection, drag-and-drop, slider scrubbing, resize handles, panel repositioning. Frontmost target: posts via `.cghidEventTap` (real cursor traces the path; required for AppKit drag sources / canvas viewports). Backgrounded target: posts via the auth-signed pid-routed path (cursor-neutral).
+List every layer-0 top-level window currently known to
+WindowServer — including off-screen ones (hidden-launched,
+minimized into the Dock, on another Space). Each record
+self-contains its owning app identity so the caller never
+has to join back against list_apps.
+
+Use this — not list_apps — for any window-level reasoning:
+"does this app have a visible window right now?", "which
+Space is this window on?", "which of this pid's windows
+is the main one?". list_apps is purely an app / launch
+surface.
+
+Per-record fields:
+
+- window_id: CGWindowID, addressable for screenshot /
+ activation / Space-move APIs.
+- pid + app_name: owning app identity.
+- title: current window title (empty string for helpers
+ and chromeless surfaces).
+- bounds: x / y / width / height, top-left origin in
+ global screen points.
+- layer: CGWindow stratum. Always 0 in the default
+ filter; reserved for future higher-layer opt-in.
+- z_index: stacking order on the current Space (higher =
+ closer to front). Cross-Space ordering is undefined.
+- is_on_screen: WindowServer's "visible on the user's
+ current Space right now" bit. False for hidden /
+ minimized / off-Space windows.
+- on_current_space: true when the window is bound to the
+ user's current Space. Omitted when the SkyLight Space
+ SPIs didn't resolve (rare; sandboxed or very old OS).
+- space_ids: every managed Space id the window is a
+ member of. Compare against current_space_id in the
+ top-level response. Omitted in the same failure modes
+ as on_current_space.
+
+Top-level fields:
+
+- windows: array of the per-window records above.
+- current_space_id: user's active Space id, or null when
+ SPI unavailable.
+
+Inputs: pid (optional — restrict to one pid's windows),
+on_screen_only (bool, default false — surface off-Space /
+minimized windows by default). Layer 0 filtering is
+always applied; menubar strips and dock shields are
+noise for every current caller.
**Arguments:**
-- `pid` (integer, required): Target process ID.
-- `from_x`, `from_y` (number, required): Drag-start in window-local screenshot pixels (top-left origin).
-- `to_x`, `to_y` (number, required): Drag-end in the same space.
-- `window_id` (integer, optional): CGWindowID the pixels were measured against. Defaults to the frontmost window of `pid`.
-- `duration_ms` (integer, optional): Wall-clock budget for the path between mouseDown and mouseUp. Default: `500`.
-- `steps` (integer, optional): Number of intermediate `mouseDragged` events linearly interpolated along the path. Default: `20`.
-- `modifier` (array of string, optional): `cmd` / `shift` / `option` / `ctrl`. Held across the entire gesture (option-drag duplicates, shift-drag constrains the axis).
-- `button` (string, optional): `left` / `right` / `middle`. Default: `left`.
-- `from_zoom` (boolean, optional): When true, all four coordinates are in the last `zoom` image's pixel space.
-
-```json
-{"pid": 844, "window_id": 10725, "from_x": 100, "from_y": 200, "to_x": 400, "to_y": 200, "duration_ms": 600}
-```
+- `on_screen_only` (boolean, optional): When true, drop windows that aren't currently on the user's Space (minimized, hidden, off-Space). Default false.
+- `pid` (integer, optional): Optional pid filter. When set, only this pid's windows are returned.
### move_cursor
-Warp the real mouse cursor to a screen-point coordinate. Does not click.
+Instantly move the mouse cursor to (x, y) in screen points.
+Uses CGWarpMouseCursorPosition — no drag, no click, no CGEvent.
**Arguments:**
@@ -207,266 +528,506 @@ Warp the real mouse cursor to a screen-point coordinate. Does not click.
- `y` (integer, required): Y in screen points.
```json
-{"x": 640, "y": 400}
+{"x":100,"y":200}
```
-### scroll
-
-Synthesize PageUp/PageDown/arrow keystrokes against the target pid. When `element_index` is provided, the element is focused before the keystrokes fire.
+### page
-**Arguments:**
+Browser page primitives — execute JavaScript, extract page text, or query DOM elements via CSS selector.
-- `pid` (integer, required): Target process ID.
-- `direction` (string, required): `up` | `down` | `left` | `right`.
-- `amount` (integer, optional): Keystroke repetitions, 1-50. Default 3.
-- `by` (string, optional): `line` | `page`. Default `line`.
-- `element_index` (integer, optional): Requires `window_id`.
-- `window_id` (integer, optional): Required when `element_index` is used.
+Three actions:
-```json
-{"pid": 844, "direction": "down", "amount": 5, "by": "page"}
-```
+• `execute_javascript` — run arbitrary JS in the active tab and return the result. Wrap in an IIFE with try-catch for safety. Don't use this for elements already indexed by `get_window_state` — prefer `click` / `set_value` there.
-## Keyboard and text
+• `get_text` — returns `document.body.innerText`. Faster than walking the AX tree for plain-text content (prices, article body, table values) that the AX tree drops or truncates.
-All keyboard tools are pid-scoped: the event is delivered to the target process regardless of current frontmost app.
+• `query_dom` — runs `querySelectorAll(css_selector)` and returns each matching element's tag, innerText, and any requested attributes as a JSON array. Useful for structured data (table rows, link hrefs, data-* attributes) that the AX tree flattens.
-### press_key
+Supported browsers: Chrome (com.google.Chrome), Brave (com.brave.Browser), Edge (com.microsoft.edgemac), Safari (com.apple.Safari). Requires "Allow JavaScript from Apple Events" enabled — see WEB_APPS.md.
-Single key press, optionally with modifiers. Delivered via `CGEvent.postToPid`.
+`pid` and `window_id` identify the target window. The browser does NOT need to be frontmost for read actions. For mutations that trigger UI changes (form submits, navigation) the browser should be frontmost so the results are visible.
**Arguments:**
-- `pid` (integer, required): Target process ID.
-- `key` (string, required): Key name: `return`, `tab`, `escape`, `up`, `down`, `left`, `right`, `space`, `delete`, `home`, `end`, `pageup`, `pagedown`, `f1`-`f12`, letter, digit.
-- `modifiers` (array of string, optional): `cmd` / `shift` / `option` / `ctrl` / `fn` held while the key is pressed.
-- `element_index` (integer, optional): When present, the element is focused before the key fires. Requires `window_id`.
-- `window_id` (integer, optional): Required when `element_index` is used.
+- `action` (string, required): Which page primitive to run.
+
+• execute_javascript / get_text / query_dom — see above.
+• enable_javascript_apple_events — enable 'Allow JavaScript from Apple Events' in Chrome/Brave/Edge. Quits the browser, patches each profile's Preferences JSON, then relaunches. Requires user_has_confirmed_enabling=true — you MUST ask the user for explicit permission before calling this action.
+- `attributes` (array of string, optional): Element attributes to include per match (action=query_dom only). E.g. ["href", "src", "data-id"]. tag and innerText are always included.
+- `bundle_id` (string, optional): Browser bundle ID (action=enable_javascript_apple_events only). E.g. com.google.Chrome.
+- `css_selector` (string, optional): CSS selector (action=query_dom only). Passed to querySelectorAll — standard CSS syntax.
+- `javascript` (string, optional): JS to execute (action=execute_javascript only). Should return a serialisable value. Wrap in IIFE: `(() => { … })()`.
+- `pid` (integer, required): Browser process ID.
+- `user_has_confirmed_enabling` (boolean, optional): Must be true (action=enable_javascript_apple_events only). Set this only after the user has explicitly said yes to enabling JavaScript from Apple Events.
+- `window_id` (integer, required): CGWindowID of the target browser window.
```json
-{"pid": 844, "key": "return"}
+{"action":"get_text","pid":844,"window_id":10725}
```
-### hotkey
+### press_key
-Modifier combo as a single array, e.g. `["cmd", "c"]`. Requires at least two entries (one or more modifiers plus one non-modifier key).
+Press and release a single key, delivered directly to the
+target pid's event queue via `CGEvent.postToPid`. The target
+does NOT need to be frontmost — no focus steal.
+
+Optional `element_index` + `window_id` (from the last
+`get_window_state` snapshot of that window) pre-focuses
+that element (via `AXSetAttribute(kAXFocused, true)`)
+before the key fires; useful for "type into field →
+press Return on field." Without `element_index`, the
+key is posted to the pid with whatever element is
+already focused receiving it — useful for scroll keys
+on a backgrounded web view.
+
+The key is delivered via SkyLight's `SLEventPostToPid`
+with an attached `SLSEventAuthenticationMessage`,
+which is the path the renderer's keyboard pipeline
+accepts as authentic input. That's what lets Return
+commit a Chromium omnibox against a backgrounded
+window. Falls back to the public `CGEventPostToPid`
+when the SkyLight SPI isn't available.
+
+Key vocabulary: return, tab, escape, up/down/left/right,
+space, delete, home, end, pageup, pagedown, f1-f12, plus
+any letter or digit. Optional `modifiers` array takes
+cmd/shift/option/ctrl/fn. For true combinations (cmd+c),
+`hotkey` is a cleaner surface.
**Arguments:**
+- `element_index` (integer, optional): Optional element_index from the last get_window_state for the same (pid, window_id). When present, the element is focused before the key fires. Requires window_id.
+- `key` (string, required): Key name (return, tab, escape, up, down, left, right, space, delete, home, end, pageup, pagedown, f1-f12, letter, digit).
+- `modifiers` (array of string, optional): Optional modifier names held while the key is pressed (cmd/shift/option/ctrl/fn).
- `pid` (integer, required): Target process ID.
-- `keys` (array of string, required): Modifier(s) and one non-modifier key.
+- `window_id` (integer, optional): CGWindowID for the window whose get_window_state produced the element_index. Required when element_index is used.
```json
-{"pid": 844, "keys": ["cmd", "shift", "s"]}
+{"key":"return","pid":844}
```
-### type_text
+### replay_trajectory
-Insert text at the target's current cursor. Attempts `AXSelectedText` write first (fast, single AX call); automatically falls back to character-by-character `CGEvent.postToPid` synthesis when the target input doesn't implement `AXSelectedText` — this makes it work for Chromium and Electron inputs without any manual switching.
+Replay a recorded trajectory by re-invoking every turn's
+tool call in lexical order. `dir` must point at a
+directory previously written by `set_recording` (or the
+`cua-driver recording start` CLI). Each `turn-NNNNN/`
+is parsed for `action.json`, and the recorded tool is
+called with its recorded `arguments` via the same
+dispatch path an MCP / CLI call uses.
+
+Caveats:
+
+- Element-indexed actions (`click({pid, element_index})`
+ etc.) will fail because element indices are
+ per-snapshot and don't survive across sessions. Pixel
+ clicks (`click({pid, x, y})`) and all keyboard tools
+ replay cleanly. Failures are reported but don't stop
+ replay unless `stop_on_error` is true.
+- `get_window_state` and other read-only tools are NOT
+ currently recorded, so replays do not re-populate the
+ per-(pid, window_id) element cache. A recorded session
+ consisting solely of element-indexed clicks will
+ therefore replay as a stream of "No cached AX state"
+ errors — fine for regression diffs, useless for
+ re-driving an app.
+- If recording is ENABLED while replay runs, the replay
+ itself is recorded into the currently configured
+ output directory. That's deliberate: recording a
+ replay against a new build and diffing the two
+ trajectories is the regression-test workflow.
**Arguments:**
-- `pid` (integer, required): Target process ID.
-- `text` (string, required): Text to insert at the target's cursor.
-- `element_index` (integer, optional): When present, the element is focused before the write. Requires `window_id`.
-- `window_id` (integer, optional): Required when `element_index` is used.
-- `delay_ms` (integer, optional): Milliseconds between characters when the CGEvent fallback path is used, 0-200. Default 30.
+- `delay_ms` (integer, optional): Milliseconds to sleep between turns, for human-observable pacing. Default 500.
+- `dir` (string, required): Trajectory directory previously written by `set_recording`. Absolute or ~-rooted.
+- `stop_on_error` (boolean, optional): Stop replay on the first tool-call error. Default true — set false to best-effort through the full trajectory.
```json
-{"pid": 844, "window_id": 10725, "element_index": 12, "text": "hello"}
-{"pid": 844, "text": "hello world", "delay_ms": 40}
+{"dir":"~/cua-trajectories/demo1"}
```
-## Element values
-
-### set_value
+### right_click
-Write an element's `AXValue` directly. For sliders, steppers, text fields, and similar controls where AX coerces the string to the native type.
+Right-click against a target pid. Two addressing modes:
+
+- `element_index` + `window_id` (from the last
+ `get_window_state` snapshot of that window) —
+ performs `AXShowMenu` on the cached element. This is the
+ reliable path: pure AX RPC, works on backgrounded /
+ hidden windows, no cursor move or focus steal. Requires
+ a prior `get_window_state(pid, window_id)` in this turn.
+
+- `x`, `y` (window-local screenshot pixels, top-left
+ origin of the PNG returned by `get_window_state`) —
+ internally routed through AX (`AXShowMenu`) when the
+ pixel resolves to an actionable element (same
+ reliability as `element_index`); falls back to a
+ synthesized right-mouse-down / right-mouse-up
+ CGEvent pair posted via auth-signed
+ `SLEventPostToPid` for non-AX surfaces (canvas /
+ WebView / games). Driver converts image-pixel →
+ screen-point internally. Experimental on Chromium
+ web content in the CGEvent fallback: the event is
+ observed to land as a left-click there (a known
+ limitation matching third-party Computer Use
+ implementations). `modifier` forces the CGEvent
+ path (AX doesn't propagate modifier keys).
+
+Exactly one of `element_index` or (`x` AND `y`) must be
+provided. `pid` is required in both modes. `window_id`
+is required when `element_index` is used. `modifier`
+only takes effect in the pixel path (AX actions don't
+propagate modifier keys).
**Arguments:**
+- `element_index` (integer, optional): Element index from the last get_window_state for the same (pid, window_id). Routes through AXShowMenu. Requires window_id.
+- `modifier` (array of string, optional): Modifier keys held during the right-click: cmd/shift/option/ctrl. Pixel path only.
- `pid` (integer, required): Target process ID.
-- `window_id` (integer, required): CGWindowID for the window whose `get_window_state` produced `element_index`.
-- `element_index` (integer, required): Element index from the last `get_window_state` for the same `(pid, window_id)`.
-- `value` (string, required): New value. AX coerces it to the element's native type.
+- `window_id` (integer, optional): CGWindowID for the window whose get_window_state produced the element_index. Required when element_index is used; ignored in the pixel path.
+- `x` (number, optional): X in window-local screenshot pixels — same space as the PNG get_window_state returns. Top-left origin of the target's window. Must be provided together with y.
+- `y` (number, optional): Y in window-local screenshot pixels — same space as the PNG get_window_state returns. Top-left origin of the target's window. Must be provided together with x.
```json
-{"pid": 844, "window_id": 10725, "element_index": 9, "value": "42"}
+{"pid":844}
```
-## Browser
-
-### page
+### screenshot
-Browser page primitives — execute JavaScript, extract page text, or query DOM elements. Supports Chrome, Brave, Edge, and Safari (requires "Allow JavaScript from Apple Events"). For WKWebView/Tauri apps where the remote inspector is blocked, `get_text` and `query_dom` automatically fall back to the accessibility tree.
+Capture a screenshot using ScreenCaptureKit. Returns base64-encoded
+image data in the requested format (default png).
-**Arguments:**
+Without `window_id`, captures the full main display. With `window_id`,
+captures just that window (get the id from `list_windows`).
-- `pid` (integer, required): Browser process ID.
-- `window_id` (integer, required): CGWindowID of the target browser window.
-- `action` (string, required): One of `execute_javascript`, `get_text`, `query_dom`, `enable_javascript_apple_events`.
-- `javascript` (string): JS to evaluate — action `execute_javascript` only. Wrap in an IIFE with try-catch for safety.
-- `css_selector` (string): CSS selector — action `query_dom` only.
-- `attributes` (array of string, optional): Attributes to include per element — action `query_dom` only. `tag` and `text` are always included.
-- `bundle_id` (string): Browser bundle ID — action `enable_javascript_apple_events` only.
-- `user_has_confirmed_enabling` (boolean): Must be `true` — action `enable_javascript_apple_events` only. **You must ask the user for explicit permission before passing this.**
+Requires the Screen Recording TCC grant — call `check_permissions`
+first if unsure.
-```json
-{"pid": 1234, "window_id": 5678, "action": "get_text"}
-{"pid": 1234, "window_id": 5678, "action": "execute_javascript", "javascript": "document.title"}
-{"pid": 1234, "window_id": 5678, "action": "query_dom", "css_selector": "a[href]", "attributes": ["href"]}
-```
+**Arguments:**
-## Zoom
+- `format` (string, optional): Image format. Default: png.
+- `quality` (integer, optional): JPEG quality 1-95; ignored for png.
+- `window_id` (integer, optional): Optional CGWindowID / kCGWindowNumber to capture just that window.
-### zoom
+### scroll
-Native-resolution crop of a previously captured window region. Pass the region in resized-image pixel coordinates (same space `get_window_state` reports); the tool scales back to the source resolution, pads by 20% on each side, captures the frontmost window of `pid`, and returns the crop.
+Scroll the target pid's focused region by synthesized
+keystrokes.
+
+Mapping: `by: "page"` → PageDown/PageUp × amount;
+`by: "line"` → DownArrow/UpArrow × amount. Horizontal
+variants use Left/Right arrow keys. Keys are posted via
+the same auth-signed `SLEventPostToPid` path as
+`press_key`, so backgrounded Chromium / WebKit windows
+scroll correctly.
+
+Why keyboard instead of wheel events: probe tests
+showed `CGEventCreateScrollWheelEvent2` posted via
+SkyLight's per-pid path is silently dropped by
+Chromium (no Scroll-specific auth subclass exists;
+the factory falls back to the bare parent class and
+renderers reject it). Keystrokes don't have that
+problem — that's why PageDown works when the wheel
+event didn't.
+
+Optional `element_index` + `window_id` (from the last
+`get_window_state` snapshot of that window) focuses the
+element (`AXFocused=true`) before the keystroke, so the
+keys land in the scrollable element rather than whatever
+previously had focus. Skip it if focus was already
+established by a prior click.
**Arguments:**
+- `amount` (integer, optional): Number of keystroke repetitions. Default: 3.
+- `by` (string, optional): Scroll granularity. Default: line.
+- `direction` (string, required):
+- `element_index` (integer, optional): Optional element_index from the last get_window_state for the same (pid, window_id) — focuses the element before the keystrokes fire. Requires window_id.
- `pid` (integer, required): Target process ID.
-- `x1` (number, required): Left edge of the region (resized-image pixels).
-- `y1` (number, required): Top edge of the region (resized-image pixels).
-- `x2` (number, required): Right edge of the region (resized-image pixels).
-- `y2` (number, required): Bottom edge of the region (resized-image pixels).
+- `window_id` (integer, optional): CGWindowID for the window whose get_window_state produced the element_index. Required when element_index is used.
```json
-{"pid": 844, "x1": 200, "y1": 100, "x2": 400, "y2": 250}
+{"direction":"down","pid":844}
```
-After `zoom`, pass `from_zoom: true` to `click` with pixel coordinates in the zoomed image; the driver maps them back automatically.
-
-## Agent cursor overlay
+### set_agent_cursor_enabled
-The agent cursor is an optional visual overlay (Bezier-arc glide + click ripple + dwell) drawn on top of every synthetic click. Motion parameters persist across restarts via the config file.
+Toggle the visual agent-cursor overlay. When enabled, future
+pointer actions animate a floating arrow to the target's
+on-screen position before firing the AX action — purely
+visual, the AX dispatch itself is unchanged. Disabling
+removes the overlay immediately.
-### get_agent_cursor_state
+Default: **enabled**. Stays on for the life of the MCP
+session / daemon; disable with `{"enabled": false}` for
+headless / CI runs where the visual isn't wanted. The
+overlay only renders when the driver has an AppKit run
+loop, which is bootstrapped by `mcp` and `serve` but not
+by one-shot CLI invocations — so this flag is a no-op in
+fresh-CLI mode.
-Read the current overlay configuration: enabled flag, motion options, glide / dwell / idle-hide timings.
+**Arguments:**
-**Arguments:** none.
+- `enabled` (boolean, required): True to show the overlay cursor; false to hide.
```json
-{}
+{"enabled":false}
```
-### set_agent_cursor_enabled
+### set_agent_cursor_motion
-Toggle the overlay. Persists to config.
+Tune the agent cursor's motion curve. All fields optional;
+only the knobs you pass change, the rest keep their
+current value. The knobs map to the cubic Bezier that the
+cursor traces between successive positions, plus the
+spring animation that settles the cursor's rotation on
+arrival.
+
+- start_handle: how far along the straight line the
+ first control point sits, as a fraction in [0, 1].
+ Lower = tight departure, higher = floppy departure.
+- end_handle: same, measured from the end point.
+- arc_size: perpendicular deflection as a fraction of
+ path length. 0 = straight line. 0.25 = modest arc.
+ 0.5 = dramatic swoop. Typical: 0.25.
+- arc_flow: asymmetry bias in [-1, 1]. Positive bulges
+ the arc toward the destination; negative toward the
+ origin; 0 is symmetric.
+- spring: settle damping in [0.3, 1.0]. 1.0 = critically
+ damped (no overshoot); 0.4 = bouncy. Typical: 0.72.
+- glide_duration_ms: wall-clock duration of each cursor
+ flight in milliseconds. Higher = slower, more
+ visible for demos / screen recordings. Typical: 750.
+- dwell_after_click_ms: pause the tool holds after
+ the click ripple before returning, letting the
+ cursor visibly rest on the target so consecutive
+ clicks read as human pacing. Only applied while
+ the cursor is enabled. Typical: 400.
+- idle_hide_ms: how long the overlay lingers after
+ the last pointer action before auto-hiding.
+ Re-armed by every click, so a burst of consecutive
+ actions keeps the cursor visible throughout. Higher
+ = more tolerant of follow-up actions without the
+ overlay popping in and out. Typical: 3000.
+
+Defaults: start_handle=0.3, end_handle=0.3, arc_size=0.25,
+arc_flow=0.0, spring=0.72, glide_duration_ms=750,
+dwell_after_click_ms=400, idle_hide_ms=3000.
**Arguments:**
-- `enabled` (boolean, required): True to show; false to hide.
-
-```json
-{"enabled": true}
-```
-
-### set_agent_cursor_motion
-
-Tune the Bezier-arc + spring motion knobs. All fields are optional; omitted fields keep their current value.
+- `arc_flow` (number, optional): Asymmetry bias in [-1, 1]. Default 0.
+- `arc_size` (number, optional): Arc deflection as fraction of path length. Default 0.25.
+- `dwell_after_click_ms` (number, optional): Pause after the click ripple in ms, for human-like pacing. Default 400.
+- `end_handle` (number, optional): End-handle fraction in [0, 1]. Default 0.3.
+- `glide_duration_ms` (number, optional): Flight duration per click in ms. Higher = slower. Default 750.
+- `idle_hide_ms` (number, optional): How long the overlay lingers after the last click before auto-hiding, in ms. Default 3000.
+- `spring` (number, optional): Settle damping in [0.3, 1]. Default 0.72.
+- `start_handle` (number, optional): Start-handle fraction in [0, 1]. Default 0.3.
### set_agent_cursor_style
-Customize the cursor's visual appearance. All fields optional; omitted fields keep their current value. Changes persist to config across restarts.
+Customize the agent-cursor's visual appearance. All fields
+optional; omitted fields keep their current value.
-**Arguments:**
+- gradient_colors: Array of CSS hex strings (#RRGGBB or
+ #RGB) defining the arrow fill gradient from tip to tail.
+ E.g. ["#FF6B6B", "#FF8E53"] for a red-orange arrow.
+- bloom_color: CSS hex string for the glow halo and the
+ focus-rect highlight drawn around clicked elements.
+- image_path: Absolute or ~-rooted path to a PNG, JPEG,
+ PDF, or SVG file. When set, replaces the default arrow
+ with this image (drawn at shapeSize × shapeSize points,
+ rotated to match the motion heading). Set to "" (empty
+ string) to revert to the procedural arrow.
-- `gradient_colors` (array of string, optional): CSS hex color strings (`#RRGGBB` or `#RGB`) defining the arrow fill gradient from tip to tail. Pass an empty array `[]` to revert to the default.
-- `bloom_color` (string, optional): CSS hex color for the bloom halo and the focus-rect highlight around clicked elements. Pass `""` to revert.
-- `image_path` (string, optional): Absolute or `~`-rooted path to a PNG, JPEG, PDF, or SVG file. When set, replaces the default procedural arrow. Pass `""` to revert to the arrow.
+Example — brand-colored arrow:
+ {"gradient_colors": ["#A855F7", "#6366F1"], "bloom_color": "#A855F7"}
-```json
-{"gradient_colors": ["#A855F7", "#6366F1"], "bloom_color": "#A855F7"}
-{"image_path": "~/cursors/my-cursor.png"}
-{"gradient_colors": [], "bloom_color": "", "image_path": ""}
-```
+Example — custom PNG cursor:
+ {"image_path": "~/cursors/my-cursor.png"}
+
+Example — revert to default:
+ {"gradient_colors": [], "bloom_color": "", "image_path": ""}
**Arguments:**
-- `start_handle` (number, optional): Start-handle fraction in [0, 1]. Default 0.3.
-- `end_handle` (number, optional): End-handle fraction in [0, 1]. Default 0.3.
-- `arc_size` (number, optional): Arc deflection as fraction of path length. Default 0.25.
-- `arc_flow` (number, optional): Asymmetry bias in [-1, 1]. Default 0.
-- `spring` (number, optional): Settle damping in [0.3, 1]. Default 0.72.
-- `glide_duration_ms` (number, optional): Flight duration per click, 50-5000. Default 750.
-- `dwell_after_click_ms` (number, optional): Pause after the click ripple, 0-5000. Default 400.
-- `idle_hide_ms` (number, optional): Overlay linger after last click before auto-hide, 100-60000. Default 3000.
+- `bloom_color` (string, optional): CSS hex color for the bloom halo and focus rect. Empty string reverts to default.
+- `gradient_colors` (array of string, optional): CSS hex color strings for gradient stops (tip to tail). Empty array reverts to default.
+- `image_path` (string, optional): Path to PNG/JPEG/PDF/SVG cursor image. Empty string reverts to arrow.
-```json
-{"arc_size": 0.3, "glide_duration_ms": 900}
-```
+### set_config
-## Config
+Write a single setting into the persistent driver config
+at `~/Library/Application Support/<app-name>/config.json`.
+Values survive daemon restarts AND are propagated to the
+live session state.
-Persistent settings live at `~/Library/Application Support/Cua Driver/config.json`. Writes route through the running daemon when reachable so live state (e.g. `AgentCursor.shared`) picks up changes without a restart.
+Keys are dotted snake_case paths:
+ - `agent_cursor.enabled` (bool)
+ - `agent_cursor.motion.start_handle` (number)
+ - `agent_cursor.motion.end_handle` (number)
+ - `agent_cursor.motion.arc_size` (number)
+ - `agent_cursor.motion.arc_flow` (number)
+ - `agent_cursor.motion.spring` (number)
+ - `capture_mode` (string: `vision` | `ax` | `som`)
-### get_config
+Arguments: `{"key": "<dotted.path>", "value": <json>}`.
-Return the current config as pretty-printed JSON, identical to the on-disk shape.
+**Arguments:**
-**Arguments:** none.
+- `key` (string, required): Dotted snake_case path to a leaf config field, e.g. `agent_cursor.enabled`.
+- `value` (undefined, required): New value for `key`. JSON type depends on the key.
```json
-{}
+{"key":"return","value":"value"}
```
-### set_config
+### set_recording
-Write a single leaf field identified by a dotted `snake_case` path.
+Toggle trajectory recording. When enabled, every
+subsequent action-tool invocation (click, right_click,
+scroll, type_text, type_text_chars, press_key, hotkey,
+set_value) writes a turn folder under `output_dir`:
+
+- `app_state.json` — post-action AX snapshot for the
+ target pid (same shape as `get_window_state`).
+- `screenshot.png` — post-action per-window screenshot
+ of the target's frontmost on-screen window.
+- `action.json` — tool name, full input arguments,
+ result summary, pid, click point (when applicable),
+ ISO-8601 timestamp.
+- `click.png` — for click-family actions only,
+ `screenshot.png` with a red dot drawn at the click
+ point.
+
+Turn folders are named `turn-00001/`, `turn-00002/`,
+etc. Turn numbering restarts at 1 each time recording
+is (re-)enabled.
+
+Required when `enabled=true`: `output_dir`. Expands `~`
+and creates the directory (and intermediates) if
+missing. Ignored when `enabled=false`.
+
+State persists for the life of the daemon / MCP
+session; a restart resets to disabled with no
+on-disk state.
**Arguments:**
-- `key` (string, required): Dotted `snake_case` path to a leaf config field, e.g. `agent_cursor.enabled`.
-- `value` (required): New value. JSON type depends on the key.
+- `enabled` (boolean, required): True to start recording subsequent action tool calls; false to stop.
+- `output_dir` (string, optional): Absolute or ~-rooted directory where turn folders are written. Required when enabled=true.
+- `video_experimental` (boolean, optional): Experimental: also capture the main display to `<output_dir>/recording.mp4` via SCStream (H.264, 30fps, no audio, no cursor). Capture-only — no zoom / post-process. Off by default. Ignored when enabled=false.
```json
-{"key": "capture_mode", "value": "ax"}
+{"enabled":false}
```
-Supported keys and ranges: see the [CLI reference](/cua-driver/reference/cli-reference#cua-driver-config).
+### set_value
-## Recording and replay
+Set a value on a UI element. Two modes depending on element role:
-The trajectory recorder captures every action-tool call (`click`, `right_click`, `scroll`, `type_text`, `press_key`, `hotkey`, `set_value`) into numbered turn folders. Recordings can be replayed turn-by-turn.
+- **AXPopUpButton / select dropdown**: finds the child option whose
+ title or value matches `value` (case-insensitive) and AXPresses it
+ directly — the native macOS popup menu is never opened, so focus
+ is never stolen. Use this for HTML <select> elements in Safari or
+ any native NSPopUpButton. Pass the option's display label as `value`
+ (e.g. "Blue", not "blue").
-### get_recording_state
+- **All other elements**: writes `AXValue` directly (sliders, steppers,
+ date pickers, native text fields that expose settable AXValue).
-Report whether the recorder is currently enabled, the output directory, and the next turn number.
+For free-form text entry into web inputs, prefer `type_text_chars`
+which synthesises key events — AXValue writes are ignored by WebKit.
-**Arguments:** none.
+**Arguments:**
+
+- `element_index` (integer, required):
+- `pid` (integer, required):
+- `value` (string, required): New value. AX will coerce to the element's native type.
+- `window_id` (integer, required): CGWindowID for the window whose get_window_state produced the element_index. The element_index cache is scoped per (pid, window_id).
```json
-{}
+{"element_index":14,"pid":844,"value":"42","window_id":10725}
```
-Structured-content response: `{"enabled": bool, "next_turn": int, "output_dir"?: string}`.
+### type_text
-### set_recording
+Insert text into the target pid. Tries
+`AXSetAttribute(kAXSelectedText)` first (fast bulk insert —
+works for standard Cocoa text fields). If the target element
+rejects the AX write, automatically falls back to
+character-by-character `CGEvent.postToPid` synthesis —
+reaches Chromium / Electron inputs and any surface that
+doesn't implement `kAXSelectedText`.
+
+Special keys (Return, Escape, arrows, Tab) go through
+`press_key` / `hotkey` — they are not text.
+
+Optional `element_index` + `window_id` (from the last
+`get_window_state` snapshot of that window) pre-focuses
+that element before the write; useful for "fill this
+specific field." Without `element_index`, the write
+targets the pid's currently-focused element — useful
+after a prior click already set focus.
-Toggle the recorder. When enabling, `output_dir` is required.
+`delay_ms` (0–200, default 30) spaces successive characters
+in the CGEvent fallback path so autocomplete and IME can keep
+up; ignored when the AX path succeeds.
+
+Requires Accessibility.
**Arguments:**
-- `enabled` (boolean, required): True to start; false to stop.
-- `output_dir` (string, optional): Absolute or `~`-rooted directory for turn folders. Required when `enabled=true`.
-- `video_experimental` (boolean, optional): Experimental: also capture the main display to `<output_dir>/recording.mp4` via SCStream (H.264, 30fps, no audio, no cursor). Off by default. Ignored when `enabled=false`.
+- `delay_ms` (integer, optional): Milliseconds between characters in the CGEvent fallback path. Default 30. Ignored when the AX path succeeds.
+- `element_index` (integer, optional): Optional element_index from the last get_window_state for the same (pid, window_id). When present, the element is focused before the write. Requires window_id.
+- `pid` (integer, required): Target process ID.
+- `text` (string, required): Text to insert at the target's cursor.
+- `window_id` (integer, optional): CGWindowID for the window whose get_window_state produced the element_index. Required when element_index is used.
```json
-{"enabled": true, "output_dir": "~/cua-trajectories/demo1"}
+{"pid":844,"text":"hello"}
```
-### replay_trajectory
+### zoom
-Re-invoke every turn's tool call in lexical order against the live system.
+Zoom into a rectangular region of a window screenshot at
+full (native) resolution. Use this when `get_window_state`
+returned a resized image and you need to read small text,
+identify icons, or verify UI details.
+
+Coordinates `x1, y1, x2, y2` are in the same pixel space
+as the screenshot returned by `get_window_state` (i.e. the
+resized image if `max_image_dimension` is active). The
+maximum zoom region width is 500 px in scaled-image
+coordinates.
+
+The tool maps coordinates back to original (native)
+resolution by multiplying by the compression ratio z
+(original_size / scaled_size). A 500 px-wide region in
+the scaled image becomes 500 × z native pixels, so the
+returned image will be *larger* than 500 px whenever the
+unzoomed screenshot was downscaled. This is the intended
+behaviour — the zoom undoes the compression and shows
+the region at full pixel density.
+
+A 20% padding is automatically added on every side of
+the requested region so the target remains visible even
+if the caller's coordinates are slightly off. The
+padding is clamped to the image bounds.
+
+Requires `get_window_state(pid, window_id)` earlier in this
+session so the resize ratio is known.
**Arguments:**
-- `dir` (string, required): Trajectory directory previously written by `set_recording`. Absolute or `~`-rooted.
-- `delay_ms` (integer, optional): Milliseconds to sleep between turns, 0-10000. Default 500.
-- `stop_on_error` (boolean, optional): Stop replay on the first tool-call error. Default true; set false to best-effort through the full trajectory.
+- `pid` (integer, required): Target process ID.
+- `x1` (number, required): Left edge of the region (resized-image pixels).
+- `x2` (number, required): Right edge of the region (resized-image pixels).
+- `y1` (number, required): Top edge of the region (resized-image pixels).
+- `y2` (number, required): Bottom edge of the region (resized-image pixels).
```json
-{"dir": "~/cua-trajectories/demo1", "delay_ms": 800, "stop_on_error": false}
+{"pid":844,"x1":100,"x2":100,"y1":200,"y2":200}
```
diff --git a/libs/cua-driver/Sources/CuaDriverCLI/CuaDriverCommand.swift b/libs/cua-driver/Sources/CuaDriverCLI/CuaDriverCommand.swift
index 43268dfff2..fe86efbb06 100644
--- a/libs/cua-driver/Sources/CuaDriverCLI/CuaDriverCommand.swift
+++ b/libs/cua-driver/Sources/CuaDriverCLI/CuaDriverCommand.swift
@@ -24,6 +24,7 @@ struct CuaDriverCommand: AsyncParsableCommand {
UpdateCommand.self,
DiagnoseCommand.self,
DoctorCommand.self,
+ DumpDocsCommand.self,
]
)
}
@@ -173,6 +174,7 @@ struct CuaDriverEntryPoint {
"update",
"diagnose",
"doctor",
+ "dump-docs",
"help",
]
diff --git a/libs/cua-driver/Sources/CuaDriverCLI/Docs/CLIDocExtractor.swift b/libs/cua-driver/Sources/CuaDriverCLI/Docs/CLIDocExtractor.swift
new file mode 100644
index 0000000000..9fc9aedbe8
--- /dev/null
+++ b/libs/cua-driver/Sources/CuaDriverCLI/Docs/CLIDocExtractor.swift
@@ -0,0 +1,481 @@
+import CuaDriverCore
+import Foundation
+
+// MARK: - Documentation Types
+
+/// Represents documentation for a single CLI command
+struct CommandDoc: Codable {
+ let name: String
+ let abstract: String
+ let discussion: String?
+ let arguments: [ArgumentDoc]
+ let options: [OptionDoc]
+ let flags: [FlagDoc]
+ let subcommands: [CommandDoc]
+}
+
+/// Represents documentation for a command argument
+struct ArgumentDoc: Codable {
+ let name: String
+ let help: String
+ let type: String
+ let isOptional: Bool
+}
+
+/// Represents documentation for a command option
+struct OptionDoc: Codable {
+ let name: String
+ let shortName: String?
+ let help: String
+ let type: String
+ let defaultValue: String?
+ let isOptional: Bool
+}
+
+/// Represents documentation for a command flag
+struct FlagDoc: Codable {
+ let name: String
+ let shortName: String?
+ let help: String
+ let defaultValue: Bool
+}
+
+/// Root documentation structure
+struct CLIDocumentation: Codable {
+ let name: String
+ let version: String
+ let abstract: String
+ let commands: [CommandDoc]
+}
+
+// MARK: - CLI Documentation Extractor
+
+/// Extracts CLI documentation from command definitions.
+/// This uses a combination of ArgumentParser's configuration metadata
+/// and manually maintained help text to provide accurate documentation.
+enum CLIDocExtractor {
+ /// Extract documentation from all registered commands
+ static func extractAll() -> CLIDocumentation {
+ return CLIDocumentation(
+ name: "cua-driver",
+ version: CuaDriverCore.version,
+ abstract: "macOS Accessibility-driven computer-use agent — MCP stdio server.",
+ commands: allCommandDocs
+ )
+ }
+
+ // MARK: - Command Documentation Definitions
+
+ private static var allCommandDocs: [CommandDoc] {
+ return [
+ mcpDoc,
+ callDoc,
+ listToolsDoc,
+ describeDoc,
+ serveDoc,
+ stopDoc,
+ statusDoc,
+ recordingDoc,
+ configDoc,
+ mcpConfigDoc,
+ updateDoc,
+ diagnoseDoc,
+ doctorDoc,
+ dumpDocsDoc,
+ ]
+ }
+
+ // MARK: - mcp
+
+ private static var mcpDoc: CommandDoc {
+ CommandDoc(
+ name: "mcp",
+ abstract: "Run the stdio MCP server.",
+ discussion: nil,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: []
+ )
+ }
+
+ // MARK: - call
+
+ private static var callDoc: CommandDoc {
+ CommandDoc(
+ name: "call",
+ abstract: "Invoke an MCP tool directly from the shell.",
+ discussion: """
+ 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: [
+ ArgumentDoc(name: "tool-name", help: "Name of the tool to invoke (see `cua-driver list-tools`).", type: "String", isOptional: false),
+ ArgumentDoc(name: "json-args", help: "JSON object string for the tool's inputSchema. If omitted, reads from stdin when stdin is a pipe.", type: "String", isOptional: true),
+ ],
+ options: [
+ OptionDoc(name: "screenshot-out-file", shortName: nil, help: "Write the first image content block from the response to this file path.", type: "String", defaultValue: nil, isOptional: true),
+ OptionDoc(name: "socket", shortName: nil, help: "Override the daemon Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [
+ FlagDoc(name: "raw", shortName: nil, help: "Print the raw CallTool.Result JSON (content + structuredContent + isError) instead of unwrapping structuredContent.", defaultValue: false),
+ FlagDoc(name: "compact", shortName: nil, help: "Emit minified JSON instead of pretty-printed.", defaultValue: false),
+ FlagDoc(name: "no-daemon", shortName: nil, help: "Skip the cua-driver daemon even if one is running.", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
+
+ // MARK: - list-tools
+
+ private static var listToolsDoc: CommandDoc {
+ CommandDoc(
+ name: "list-tools",
+ abstract: "List every tool exposed by cua-driver with its one-line description.",
+ discussion: nil,
+ arguments: [],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the daemon Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [
+ FlagDoc(name: "no-daemon", shortName: nil, help: "Skip the cua-driver daemon even if one is running.", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
+
+ // MARK: - describe
+
+ private static var describeDoc: CommandDoc {
+ CommandDoc(
+ name: "describe",
+ abstract: "Print a tool's full description and JSON input schema.",
+ discussion: nil,
+ arguments: [
+ ArgumentDoc(name: "tool-name", help: "Name of the tool to describe.", type: "String", isOptional: false),
+ ],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the daemon Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [
+ FlagDoc(name: "compact", shortName: nil, help: "Emit minified JSON instead of pretty-printed.", defaultValue: false),
+ FlagDoc(name: "no-daemon", shortName: nil, help: "Skip the cua-driver daemon even if one is running.", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
+
+ // MARK: - serve
+
+ private static var serveDoc: CommandDoc {
+ CommandDoc(
+ name: "serve",
+ abstract: "Run cua-driver as a long-running daemon on a Unix domain socket.",
+ discussion: """
+ 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.
+ """,
+ arguments: [],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [
+ FlagDoc(name: "no-relaunch", shortName: nil, help: "Stay in the current process instead of re-execing via `open -n -g -a CuaDriver`.", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
+
+ // MARK: - stop
+
+ private static var stopDoc: CommandDoc {
+ CommandDoc(
+ name: "stop",
+ abstract: "Ask the running cua-driver daemon to exit gracefully.",
+ discussion: nil,
+ arguments: [],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [],
+ subcommands: []
+ )
+ }
+
+ // MARK: - status
+
+ private static var statusDoc: CommandDoc {
+ CommandDoc(
+ name: "status",
+ abstract: "Report whether a cua-driver daemon is running.",
+ discussion: nil,
+ arguments: [],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ OptionDoc(name: "pid-file", shortName: nil, help: "Override the daemon pid-file path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [],
+ subcommands: []
+ )
+ }
+
+ // MARK: - recording
+
+ private static var recordingDoc: CommandDoc {
+ CommandDoc(
+ name: "recording",
+ abstract: "Control the trajectory recorder on a running cua-driver daemon.",
+ discussion: """
+ 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.
+ """,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: [
+ CommandDoc(
+ name: "start",
+ abstract: "Enable trajectory recording to the given directory.",
+ discussion: nil,
+ arguments: [
+ ArgumentDoc(name: "output-dir", help: "Directory to write turn folders into. Expands `~`; created if missing.", type: "String", isOptional: false),
+ ],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the daemon Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [
+ FlagDoc(name: "video-experimental", shortName: nil, help: "Also capture the main display to `<output-dir>/recording.mp4` via SCStream. Experimental, off by default.", defaultValue: false),
+ ],
+ subcommands: []
+ ),
+ CommandDoc(
+ name: "stop",
+ abstract: "Disable trajectory recording.",
+ discussion: nil,
+ arguments: [],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the daemon Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [],
+ subcommands: []
+ ),
+ CommandDoc(
+ name: "status",
+ abstract: "Report whether recording is currently enabled.",
+ discussion: nil,
+ arguments: [],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the daemon Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [],
+ subcommands: []
+ ),
+ CommandDoc(
+ name: "render",
+ abstract: "Render a captured recording directory to a zoomed MP4.",
+ discussion: """
+ 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: [
+ ArgumentDoc(name: "input-dir", help: "Recording directory (contains session.json + recording.mp4 + cursor.jsonl + turn-*/).", type: "String", isOptional: false),
+ ],
+ options: [
+ OptionDoc(name: "output", shortName: nil, help: "Destination path for the rendered MP4. Overwrites any existing file.", type: "String", defaultValue: nil, isOptional: false),
+ OptionDoc(name: "scale", shortName: nil, help: "Zoom factor applied to each click event. 1.0 disables zoom; 2.0 is 2× magnification.", type: "Double", defaultValue: "2.0", isOptional: true),
+ ],
+ flags: [
+ FlagDoc(name: "no-zoom", shortName: nil, help: "Skip the zoom curve and re-encode the input as-is. Useful as a baseline check.", defaultValue: false),
+ ],
+ subcommands: []
+ ),
+ ]
+ )
+ }
+
+ // MARK: - config
+
+ private static var configDoc: CommandDoc {
+ CommandDoc(
+ name: "config",
+ abstract: "Read and write persistent cua-driver settings.",
+ discussion: """
+ 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
+ """,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: [
+ CommandDoc(
+ name: "show",
+ abstract: "Print the full current config as JSON.",
+ discussion: nil,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: []
+ ),
+ CommandDoc(
+ name: "get",
+ abstract: "Print a single config value by key.",
+ discussion: nil,
+ arguments: [
+ ArgumentDoc(name: "key", help: "Config key to read (e.g. `schema_version`, `agent_cursor.enabled`).", type: "String", isOptional: false),
+ ],
+ options: [],
+ flags: [],
+ subcommands: []
+ ),
+ CommandDoc(
+ name: "set",
+ abstract: "Write a single config value by dotted snake_case key.",
+ discussion: nil,
+ arguments: [
+ ArgumentDoc(name: "key", help: "Dotted snake_case path, e.g. `agent_cursor.enabled` or `agent_cursor.motion.arc_size`.", type: "String", isOptional: false),
+ ArgumentDoc(name: "value", help: "New value. JSON type depends on the key.", type: "String", isOptional: false),
+ ],
+ options: [
+ OptionDoc(name: "socket", shortName: nil, help: "Override the daemon Unix socket path.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [],
+ subcommands: []
+ ),
+ CommandDoc(
+ name: "reset",
+ abstract: "Overwrite the config file with defaults.",
+ discussion: nil,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: []
+ ),
+ CommandDoc(
+ name: "telemetry",
+ abstract: "Manage anonymous telemetry settings.",
+ discussion: nil,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: [
+ CommandDoc(name: "status", abstract: "Show whether anonymous telemetry is enabled.", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),
+ CommandDoc(name: "enable", abstract: "Enable anonymous telemetry.", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),
+ CommandDoc(name: "disable", abstract: "Disable anonymous telemetry.", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),
+ ]
+ ),
+ CommandDoc(
+ name: "updates",
+ abstract: "Manage automatic update settings.",
+ discussion: nil,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: [
+ CommandDoc(name: "status", abstract: "Show whether automatic updates are enabled.", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),
+ CommandDoc(name: "enable", abstract: "Enable automatic updates.", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),
+ CommandDoc(name: "disable", abstract: "Disable automatic updates.", discussion: nil, arguments: [], options: [], flags: [], subcommands: []),
+ ]
+ ),
+ ]
+ )
+ }
+
+ // MARK: - mcp-config
+
+ private static var mcpConfigDoc: CommandDoc {
+ CommandDoc(
+ name: "mcp-config",
+ abstract: "Print MCP server config or a client-specific install command.",
+ discussion: nil,
+ arguments: [],
+ options: [
+ OptionDoc(name: "client", shortName: nil, help: "Client to print the install command for: claude | codex | cursor | openclaw | opencode | hermes | pi. Omit for the generic JSON snippet.", type: "String", defaultValue: nil, isOptional: true),
+ ],
+ flags: [],
+ subcommands: []
+ )
+ }
+
+ // MARK: - update
+
+ private static var updateDoc: CommandDoc {
+ CommandDoc(
+ name: "update",
+ abstract: "Check for a newer cua-driver release and apply it.",
+ discussion: nil,
+ arguments: [],
+ options: [],
+ flags: [
+ FlagDoc(name: "apply", shortName: nil, help: "Download and apply the update without prompting.", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
+
+ // MARK: - diagnose
+
+ private static var diagnoseDoc: CommandDoc {
+ CommandDoc(
+ name: "diagnose",
+ abstract: "Print a paste-able bundle-path / cdhash / TCC-status report for support.",
+ discussion: nil,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: []
+ )
+ }
+
+ // MARK: - doctor
+
+ private static var doctorDoc: CommandDoc {
+ CommandDoc(
+ name: "doctor",
+ abstract: "Clean up stale install bits left from older cua-driver versions.",
+ discussion: nil,
+ arguments: [],
+ options: [],
+ flags: [],
+ subcommands: []
+ )
+ }
+
+ // MARK: - dump-docs
+
+ private static var dumpDocsDoc: CommandDoc {
+ CommandDoc(
+ name: "dump-docs",
+ abstract: "Output CLI and MCP tool documentation as JSON for tooling and integrations.",
+ discussion: nil,
+ arguments: [],
+ options: [
+ OptionDoc(name: "type", shortName: nil, help: "Documentation type: cli, mcp, or all", type: "String", defaultValue: "all", isOptional: true),
+ ],
+ flags: [
+ FlagDoc(name: "pretty", shortName: nil, help: "Pretty-print JSON output", defaultValue: false),
+ ],
+ subcommands: []
+ )
+ }
+}
diff --git a/libs/cua-driver/Sources/CuaDriverCLI/DumpDocsCommand.swift b/libs/cua-driver/Sources/CuaDriverCLI/DumpDocsCommand.swift
new file mode 100644
index 0000000000..b186190794
--- /dev/null
+++ b/libs/cua-driver/Sources/CuaDriverCLI/DumpDocsCommand.swift
@@ -0,0 +1,86 @@
+import ArgumentParser
+import CuaDriverCore
+import CuaDriverServer
+import Foundation
+
+struct DumpDocsCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "dump-docs",
+ abstract: "Output CLI and MCP tool documentation as JSON for tooling and integrations",
+ discussion: """
+ Extracts all command and MCP tool metadata including arguments, options, flags,
+ and their help text, default values, and types. Useful for generating
+ documentation or building integrations.
+
+ Examples:
+ cua-driver dump-docs # Output all docs
+ cua-driver dump-docs --type cli # Output CLI docs only
+ cua-driver dump-docs --type mcp # Output MCP tool docs only
+ cua-driver dump-docs --pretty # Pretty-print output
+ """
+ )
+
+ @Option(help: "Documentation type to output: cli, mcp, or all")
+ var type: DumpDocType = .all
+
+ @Flag(help: "Pretty-print the JSON output with indentation")
+ var pretty: Bool = false
+
+ func run() throws {
+ let encoder = JSONEncoder()
+ encoder.keyEncodingStrategy = .convertToSnakeCase
+
+ if pretty {
+ encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+ }
+
+ let jsonData: Data
+
+ switch type {
+ case .cli:
+ jsonData = try encoder.encode(CLIDocExtractor.extractAll())
+ case .mcp:
+ jsonData = try encoder.encode(MCPDocExtractor.extractAll())
+ case .all:
+ let combined = CombinedDocs(
+ cli: CLIDocExtractor.extractAll(),
+ mcp: MCPDocExtractor.extractAll()
+ )
+ jsonData = try encoder.encode(combined)
+ }
+
+ guard let jsonString = String(data: jsonData, encoding: .utf8) else {
+ throw DumpDocsError.encodingFailed
+ }
+
+ print(jsonString)
+ }
+}
+
+// MARK: - Documentation Type
+
+enum DumpDocType: String, ExpressibleByArgument, CaseIterable {
+ case cli
+ case mcp
+ case all
+}
+
+// MARK: - Combined Documentation
+
+struct CombinedDocs: Codable {
+ let cli: CLIDocumentation
+ let mcp: MCPDocumentation
+}
+
+// MARK: - Errors
+
+enum DumpDocsError: Error, CustomStringConvertible {
+ case encodingFailed
+
+ var description: String {
+ switch self {
+ case .encodingFailed:
+ return "Failed to encode documentation to JSON"
+ }
+ }
+}
diff --git a/libs/cua-driver/Sources/CuaDriverServer/Docs/MCPDocExtractor.swift b/libs/cua-driver/Sources/CuaDriverServer/Docs/MCPDocExtractor.swift
new file mode 100644
index 0000000000..30cc3c5d18
--- /dev/null
+++ b/libs/cua-driver/Sources/CuaDriverServer/Docs/MCPDocExtractor.swift
@@ -0,0 +1,37 @@
+import CuaDriverCore
+import Foundation
+import MCP
+
+// MARK: - MCP Documentation Types
+
+/// Root documentation structure for MCP tools
+public struct MCPDocumentation: Codable, Sendable {
+ public let version: String
+ public let tools: [MCPToolDoc]
+}
+
+/// Documentation for a single MCP tool
+public struct MCPToolDoc: Codable, Sendable {
+ public let name: String
+ public let description: String
+ public let inputSchema: Value
+}
+
+// MARK: - MCP Documentation Extractor
+
+/// Serializes all MCP tools from `ToolRegistry.default` into a JSON-friendly structure.
+public enum MCPDocExtractor {
+ public static func extractAll() -> MCPDocumentation {
+ let tools = ToolRegistry.default.allTools.map { tool in
+ MCPToolDoc(
+ name: tool.name,
+ description: tool.description ?? "",
+ inputSchema: tool.inputSchema
+ )
+ }
+ return MCPDocumentation(
+ version: CuaDriverCore.version,
+ tools: tools
+ )
+ }
+}
diff --git a/scripts/docs-generators/config.json b/scripts/docs-generators/config.json
index de1cb70b87..ab77634b24 100644
--- a/scripts/docs-generators/config.json
+++ b/scripts/docs-generators/config.json
@@ -2,6 +2,32 @@
"$schema": "./config.schema.json",
"description": "Configuration for auto-generating documentation from source code",
"generators": {
+ "cua-driver": {
+ "name": "Cua Driver",
+ "language": "swift",
+ "sourcePath": "libs/cua-driver/Sources",
+ "docsOutputPath": "docs/content/docs/cua-driver/reference",
+ "generatorScript": "scripts/docs-generators/cua-driver.ts",
+ "watchPaths": [
+ "libs/cua-driver/Sources/**/*.swift"
+ ],
+ "buildCommand": "swift build --configuration release",
+ "buildDirectory": "libs/cua-driver",
+ "extractionMethod": "dump-docs",
+ "outputs": [
+ {
+ "type": "mcp",
+ "outputFile": "mcp-tools.mdx",
+ "extractCommand": ".build/release/cua-driver dump-docs --type mcp"
+ },
+ {
+ "type": "cli",
+ "outputFile": "cli-reference.mdx",
+ "extractCommand": ".build/release/cua-driver dump-docs --type cli"
+ }
+ ],
+ "enabled": true
+ },
"lume": {
"name": "Lume VM Manager",
"language": "swift",
diff --git a/scripts/docs-generators/cua-driver.ts b/scripts/docs-generators/cua-driver.ts
new file mode 100644
index 0000000000..47ea4eae08
--- /dev/null
+++ b/scripts/docs-generators/cua-driver.ts
@@ -0,0 +1,714 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Cua Driver Documentation Generator
+ *
+ * Generates MDX documentation files from the cua-driver `dump-docs` command output.
+ * This ensures documentation stays synchronized with the source code.
+ *
+ * Usage:
+ * npx tsx scripts/docs-generators/cua-driver.ts # Generate docs
+ * npx tsx scripts/docs-generators/cua-driver.ts --check # Check for drift (CI mode)
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CLIDocumentation {
+ name: string;
+ version: string;
+ abstract: string;
+ commands: CommandDoc[];
+}
+
+export interface CommandDoc {
+ name: string;
+ abstract: string;
+ discussion?: string;
+ arguments: ArgumentDoc[];
+ options: OptionDoc[];
+ flags: FlagDoc[];
+ subcommands: CommandDoc[];
+}
+
+export interface ArgumentDoc {
+ name: string;
+ help: string;
+ type: string;
+ is_optional: boolean;
+}
+
+export interface OptionDoc {
+ name: string;
+ short_name?: string | null;
+ help: string;
+ type: string;
+ default_value?: string | null;
+ is_optional: boolean;
+}
+
+export interface FlagDoc {
+ name: string;
+ short_name?: string | null;
+ help: string;
+ default_value: boolean;
+}
+
+export interface MCPToolDoc {
+ name: string;
+ description: string;
+ input_schema: MCPInputSchema;
+}
+
+export interface MCPInputSchema {
+ type: string;
+ required?: string[];
+ properties?: Record<string, MCPPropertyDoc>;
+}
+
+export interface MCPPropertyDoc {
+ type: string;
+ description: string;
+ items?: { type: string };
+}
+
+export interface MCPDocumentation {
+ version: string;
+ tools: MCPToolDoc[];
+}
+
+export interface DumpDocsOutput {
+ cli: CLIDocumentation;
+ mcp: MCPDocumentation;
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const ROOT_DIR = path.resolve(__dirname, '../..');
+const CUA_DRIVER_DIR = path.join(ROOT_DIR, 'libs', 'cua-driver');
+const DOCS_OUTPUT_DIR = path.join(
+ ROOT_DIR,
+ 'docs',
+ 'content',
+ 'docs',
+ 'cua-driver',
+ 'reference'
+);
+const TAG_PREFIX = 'cua-driver-v';
+
+// ============================================================================
+// Version Discovery
+// ============================================================================
+
+interface VersionInfo {
+ version: string;
+ href: string;
+ isCurrent: boolean;
+}
+
+/**
+ * Get the latest released version from git tags.
+ */
+export function getLatestReleasedVersion(): string {
+ try {
+ const output = execSync(`git tag | grep "^${TAG_PREFIX}" | sort -V | tail -1`, {
+ encoding: 'utf-8',
+ cwd: ROOT_DIR,
+ }).trim();
+ if (output) {
+ return output.replace(TAG_PREFIX, '');
+ }
+ } catch {
+ // Fall through
+ }
+ return '0.0.0';
+}
+
+/**
+ * Discover available versioned doc folders and build version list.
+ */
+export function discoverVersions(currentVersion: string): VersionInfo[] {
+ const versions: VersionInfo[] = [];
+ const currentMajorMinor = currentVersion.split('.').slice(0, 2).join('.');
+
+ // Add current version (latest)
+ versions.push({
+ version: currentMajorMinor,
+ href: '/cua-driver/reference/cli-reference',
+ isCurrent: true,
+ });
+
+ // Discover versioned folders (v0.2, v0.1, etc.)
+ if (fs.existsSync(DOCS_OUTPUT_DIR)) {
+ const entries = fs.readdirSync(DOCS_OUTPUT_DIR, { withFileTypes: true });
+ for (const entry of entries) {
+ if (entry.isDirectory() && entry.name.startsWith('v')) {
+ const version = entry.name.substring(1);
+ if (version === currentMajorMinor) continue;
+ versions.push({
+ version,
+ href: `/cua-driver/reference/${entry.name}/cli-reference`,
+ isCurrent: false,
+ });
+ }
+ }
+ }
+
+ // Sort descending
+ versions.sort((a, b) => {
+ const partsA = a.version.split('.').map((x) => parseInt(x, 10) || 0);
+ const partsB = b.version.split('.').map((x) => parseInt(x, 10) || 0);
+ for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+ const partA = partsA[i] || 0;
+ const partB = partsB[i] || 0;
+ if (partA !== partB) return partB - partA;
+ }
+ return 0;
+ });
+
+ return versions;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+ const args = process.argv.slice(2);
+ const checkOnly = args.includes('--check') || args.includes('--check-only');
+
+ console.log('Cua Driver Documentation Generator');
+ console.log('===================================\n');
+
+ // Step 1: Build cua-driver
+ console.log('Building cua-driver...');
+ try {
+ execSync('swift build --configuration release', {
+ cwd: CUA_DRIVER_DIR,
+ stdio: 'inherit',
+ });
+ } catch (error) {
+ console.error('Failed to build cua-driver');
+ process.exit(1);
+ }
+
+ // Step 2: Extract all docs in a single invocation
+ console.log('\nExtracting documentation...');
+ const dumpDocsJson = execSync(
+ '.build/release/cua-driver dump-docs --type all --pretty',
+ {
+ cwd: CUA_DRIVER_DIR,
+ encoding: 'utf-8',
+ }
+ );
+ const dumpDocs: DumpDocsOutput = JSON.parse(dumpDocsJson);
+ console.log(` Found ${dumpDocs.cli.commands.length} CLI commands`);
+ console.log(` Found ${dumpDocs.mcp.tools.length} MCP tools`);
+
+ // Step 3: Generate MDX files
+ console.log('\nGenerating documentation files...');
+
+ const releasedVersion = getLatestReleasedVersion();
+ // Use the version embedded in the binary itself as the canonical current
+ // version — it's always correct even on unreleased branches where no git
+ // tag exists yet. Fall back to the latest released tag only when the
+ // binary reports an empty/missing version.
+ const currentVersion = dumpDocs.cli.version || dumpDocs.mcp.version || releasedVersion;
+
+ const cliMdx = generateCLIReferenceMDX(dumpDocs.cli, currentVersion);
+ const mcpMdx = generateMCPToolsMDX(dumpDocs.mcp, currentVersion);
+
+ const cliPath = path.join(DOCS_OUTPUT_DIR, 'cli-reference.mdx');
+ const mcpPath = path.join(DOCS_OUTPUT_DIR, 'mcp-tools.mdx');
+
+ if (checkOnly) {
+ // Check mode: compare with existing files
+ console.log('\nChecking for documentation drift...');
+
+ let hasDrift = false;
+
+ if (fs.existsSync(cliPath)) {
+ const existingCli = fs.readFileSync(cliPath, 'utf-8');
+ if (existingCli !== cliMdx) {
+ console.error('cli-reference.mdx is out of sync with source code');
+ hasDrift = true;
+ } else {
+ console.log('cli-reference.mdx is up to date');
+ }
+ } else {
+ console.error('cli-reference.mdx does not exist');
+ hasDrift = true;
+ }
+
+ if (fs.existsSync(mcpPath)) {
+ const existingMcp = fs.readFileSync(mcpPath, 'utf-8');
+ if (existingMcp !== mcpMdx) {
+ console.error('mcp-tools.mdx is out of sync with source code');
+ hasDrift = true;
+ } else {
+ console.log('mcp-tools.mdx is up to date');
+ }
+ } else {
+ console.error('mcp-tools.mdx does not exist');
+ hasDrift = true;
+ }
+
+ if (hasDrift) {
+ console.error("\nRun 'npx tsx scripts/docs-generators/cua-driver.ts' to update documentation");
+ process.exit(1);
+ }
+
+ console.log('\nAll cua-driver documentation is up to date!');
+ } else {
+ // Generate mode: write files
+ fs.mkdirSync(DOCS_OUTPUT_DIR, { recursive: true });
+
+ fs.writeFileSync(cliPath, cliMdx);
+ console.log(` Generated ${path.relative(ROOT_DIR, cliPath)}`);
+
+ fs.writeFileSync(mcpPath, mcpMdx);
+ console.log(` Generated ${path.relative(ROOT_DIR, mcpPath)}`);
+
+ console.log('\ncua-driver documentation generated successfully!');
+ }
+}
+
+// ============================================================================
+// CLI Reference Generator
+// ============================================================================
+
+export function generateCLIReferenceMDX(docs: CLIDocumentation, releasedVersion: string): string {
+ const lines: string[] = [];
+
+ const currentMajorMinor = releasedVersion.split('.').slice(0, 2).join('.');
+ const versions = discoverVersions(releasedVersion);
+
+ // Frontmatter — must be at the very beginning of the file
+ lines.push('---');
+ lines.push('title: CLI Reference');
+ lines.push('description: Command Line Interface reference for Cua Driver');
+ lines.push('---');
+ lines.push('');
+ lines.push(`{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: npx tsx scripts/docs-generators/cua-driver.ts
+ Source: libs/cua-driver/Sources/**/*.swift
+ Version: ${releasedVersion}
+*/}`);
+ lines.push('');
+ lines.push("import { Callout } from 'fumadocs-ui/components/callout';");
+ lines.push("import { VersionHeader } from '@/components/version-selector';");
+ lines.push('');
+
+ // Version header component
+ lines.push('<VersionHeader');
+ lines.push(` versions={${JSON.stringify(versions)}}`);
+ lines.push(` currentVersion="${currentMajorMinor}"`);
+ lines.push(` fullVersion="${releasedVersion}"`);
+ lines.push(` packageName="cua-driver"`);
+ lines.push(
+ ` installCommand="curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash"`
+ );
+ lines.push('/>');
+ lines.push('');
+
+ // Introduction
+ lines.push(`${docs.abstract}`);
+ lines.push('');
+
+ // Group commands by category
+ const toolDispatch = ['call', 'list-tools', 'describe'];
+ const daemonManagement = ['serve', 'stop', 'status', 'mcp', 'mcp-config'];
+ const trajectoryRecording = ['recording'];
+ const configuration = ['config'];
+ const diagnostics = ['diagnose', 'update', 'doctor'];
+
+ lines.push('## Tool dispatch');
+ lines.push('');
+ for (const cmd of docs.commands.filter((c) => toolDispatch.includes(c.name))) {
+ lines.push(...generateCommandDoc(cmd));
+ }
+
+ lines.push('## Daemon management');
+ lines.push('');
+ for (const cmd of docs.commands.filter((c) => daemonManagement.includes(c.name))) {
+ lines.push(...generateCommandDoc(cmd));
+ }
+
+ lines.push('## Trajectory recording');
+ lines.push('');
+ for (const cmd of docs.commands.filter((c) => trajectoryRecording.includes(c.name))) {
+ lines.push(...generateCommandDoc(cmd));
+ }
+
+ lines.push('## Configuration');
+ lines.push('');
+ for (const cmd of docs.commands.filter((c) => configuration.includes(c.name))) {
+ lines.push(...generateCommandDoc(cmd));
+ }
+
+ lines.push('## Diagnostics');
+ lines.push('');
+ for (const cmd of docs.commands.filter((c) => diagnostics.includes(c.name))) {
+ lines.push(...generateCommandDoc(cmd));
+ }
+
+ // Any commands not yet categorised above
+ const allCategorised = [
+ ...toolDispatch,
+ ...daemonManagement,
+ ...trajectoryRecording,
+ ...configuration,
+ ...diagnostics,
+ ];
+ const uncategorised = docs.commands.filter((c) => !allCategorised.includes(c.name));
+ if (uncategorised.length > 0) {
+ lines.push('## Other commands');
+ lines.push('');
+ for (const cmd of uncategorised) {
+ lines.push(...generateCommandDoc(cmd));
+ }
+ }
+
+ // Global options footer
+ lines.push('## Global options');
+ lines.push('');
+ lines.push('Available on all commands:');
+ lines.push('');
+ lines.push('- `--help` — Show help information.');
+ lines.push('- `--version` — Show version number.');
+ lines.push('');
+
+ return lines.join('\n');
+}
+
+export function generateCommandDoc(cmd: CommandDoc): string[] {
+ const lines: string[] = [];
+
+ lines.push(`### cua-driver ${cmd.name}`);
+ lines.push('');
+ lines.push(cmd.abstract);
+ lines.push('');
+
+ if (cmd.discussion) {
+ lines.push(cmd.discussion);
+ lines.push('');
+ }
+
+ // Arguments table
+ if (cmd.arguments.length > 0) {
+ lines.push('**Arguments:**');
+ lines.push('');
+ lines.push('| Name | Type | Required | Description |');
+ lines.push('| ---- | ---- | -------- | ----------- |');
+ for (const arg of cmd.arguments) {
+ const required = arg.is_optional ? 'No' : 'Yes';
+ lines.push(`| \`<${arg.name}>\` | ${escapeTableCell(arg.type)} | ${required} | ${escapeTableCell(arg.help)} |`);
+ }
+ lines.push('');
+ }
+
+ // Options table
+ if (cmd.options.length > 0) {
+ lines.push('**Options:**');
+ lines.push('');
+ lines.push('| Name | Type | Default | Description |');
+ lines.push('| ---- | ---- | ------- | ----------- |');
+ for (const opt of cmd.options) {
+ const nameCell = opt.short_name
+ ? `\`-${opt.short_name}\`, \`--${opt.name}\``
+ : `\`--${opt.name}\``;
+ const defaultVal = opt.default_value != null ? opt.default_value : '—';
+ lines.push(`| ${nameCell} | ${escapeTableCell(opt.type)} | ${escapeTableCell(defaultVal)} | ${escapeTableCell(opt.help)} |`);
+ }
+ lines.push('');
+ }
+
+ // Flags table
+ if (cmd.flags.length > 0) {
+ lines.push('**Flags:**');
+ lines.push('');
+ lines.push('| Name | Description |');
+ lines.push('| ---- | ----------- |');
+ for (const flag of cmd.flags) {
+ const nameCell = flag.short_name
+ ? `\`-${flag.short_name}\`, \`--${flag.name}\``
+ : `\`--${flag.name}\``;
+ lines.push(`| ${nameCell} | ${escapeTableCell(flag.help)} |`);
+ }
+ lines.push('');
+ }
+
+ // Subcommands
+ if (cmd.subcommands.length > 0) {
+ for (const sub of cmd.subcommands) {
+ lines.push(`#### cua-driver ${cmd.name} ${sub.name}`);
+ lines.push('');
+ lines.push(sub.abstract);
+ lines.push('');
+
+ if (sub.discussion) {
+ lines.push(sub.discussion);
+ lines.push('');
+ }
+
+ if (sub.arguments.length > 0) {
+ lines.push('**Arguments:**');
+ lines.push('');
+ lines.push('| Name | Type | Required | Description |');
+ lines.push('| ---- | ---- | -------- | ----------- |');
+ for (const arg of sub.arguments) {
+ const required = arg.is_optional ? 'No' : 'Yes';
+ lines.push(`| \`<${arg.name}>\` | ${escapeTableCell(arg.type)} | ${required} | ${escapeTableCell(arg.help)} |`);
+ }
+ lines.push('');
+ }
+
+ if (sub.options.length > 0) {
+ lines.push('**Options:**');
+ lines.push('');
+ lines.push('| Name | Type | Default | Description |');
+ lines.push('| ---- | ---- | ------- | ----------- |');
+ for (const opt of sub.options) {
+ const nameCell = opt.short_name
+ ? `\`-${opt.short_name}\`, \`--${opt.name}\``
+ : `\`--${opt.name}\``;
+ const defaultVal = opt.default_value != null ? opt.default_value : '—';
+ lines.push(`| ${nameCell} | ${escapeTableCell(opt.type)} | ${escapeTableCell(defaultVal)} | ${escapeTableCell(opt.help)} |`);
+ }
+ lines.push('');
+ }
+
+ if (sub.flags.length > 0) {
+ lines.push('**Flags:**');
+ lines.push('');
+ lines.push('| Name | Description |');
+ lines.push('| ---- | ----------- |');
+ for (const flag of sub.flags) {
+ const nameCell = flag.short_name
+ ? `\`-${flag.short_name}\`, \`--${flag.name}\``
+ : `\`--${flag.name}\``;
+ lines.push(`| ${nameCell} | ${escapeTableCell(flag.help)} |`);
+ }
+ lines.push('');
+ }
+
+ // Nested subcommands
+ if (sub.subcommands.length > 0) {
+ for (const nested of sub.subcommands) {
+ lines.push(`##### cua-driver ${cmd.name} ${sub.name} ${nested.name}`);
+ lines.push('');
+ lines.push(nested.abstract);
+ lines.push('');
+
+ if (nested.discussion) {
+ lines.push(nested.discussion);
+ lines.push('');
+ }
+
+ if (nested.arguments.length > 0) {
+ lines.push('**Arguments:**');
+ lines.push('');
+ lines.push('| Name | Type | Required | Description |');
+ lines.push('| ---- | ---- | -------- | ----------- |');
+ for (const arg of nested.arguments) {
+ const required = arg.is_optional ? 'No' : 'Yes';
+ lines.push(`| \`<${arg.name}>\` | ${escapeTableCell(arg.type)} | ${required} | ${escapeTableCell(arg.help)} |`);
+ }
+ lines.push('');
+ }
+
+ if (nested.options.length > 0) {
+ lines.push('**Options:**');
+ lines.push('');
+ lines.push('| Name | Type | Default | Description |');
+ lines.push('| ---- | ---- | ------- | ----------- |');
+ for (const opt of nested.options) {
+ const nameCell = opt.short_name
+ ? `\`-${opt.short_name}\`, \`--${opt.name}\``
+ : `\`--${opt.name}\``;
+ const defaultVal = opt.default_value != null ? opt.default_value : '—';
+ lines.push(`| ${nameCell} | ${escapeTableCell(opt.type)} | ${escapeTableCell(defaultVal)} | ${escapeTableCell(opt.help)} |`);
+ }
+ lines.push('');
+ }
+
+ if (nested.flags.length > 0) {
+ lines.push('**Flags:**');
+ lines.push('');
+ lines.push('| Name | Description |');
+ lines.push('| ---- | ----------- |');
+ for (const flag of nested.flags) {
+ const nameCell = flag.short_name
+ ? `\`-${flag.short_name}\`, \`--${flag.name}\``
+ : `\`--${flag.name}\``;
+ lines.push(`| ${nameCell} | ${escapeTableCell(flag.help)} |`);
+ }
+ lines.push('');
+ }
+ }
+ }
+ }
+ }
+
+ return lines;
+}
+
+// ============================================================================
+// MCP Tools Generator
+// ============================================================================
+
+export function generateMCPToolsMDX(docs: MCPDocumentation, releasedVersion: string): string {
+ const lines: string[] = [];
+
+ // Frontmatter — must be at the very beginning of the file
+ lines.push('---');
+ lines.push('title: MCP Tools');
+ lines.push('description: Reference for every MCP tool cua-driver exposes');
+ lines.push('---');
+ lines.push('');
+ lines.push(`{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: npx tsx scripts/docs-generators/cua-driver.ts
+ Source: libs/cua-driver/Sources/**/*.swift
+ Version: ${releasedVersion}
+*/}`);
+ lines.push('');
+ lines.push("import { Callout } from 'fumadocs-ui/components/callout';");
+ lines.push('');
+
+ // Introduction — mirror the existing hand-written header prose
+ lines.push(
+ `\`cua-driver\` exposes ${docs.tools.length} MCP tools through a single stdio server (\`cua-driver mcp\`). Every tool is also callable from the shell as \`cua-driver <name> '<JSON-args>'\`.`
+ );
+ lines.push('');
+ lines.push(
+ "Tool names are `snake_case`. Responses are MCP `CallTool.Result` envelopes: a text content block prefixed with a `✅` summary (or the error reason on failure), plus optional image or structured-content blocks on tools that produce them. See the [CLI reference](/cua-driver/reference/cli-reference) for CLI-specific flags like `--raw` and `--screenshot-out-file`."
+ );
+ lines.push('');
+ lines.push('<Callout type="info">');
+ lines.push(
+ ' Tool names here match the CLI form exactly. `cua-driver list_apps` and the MCP `list_apps` tool run the same code path.'
+ );
+ lines.push('</Callout>');
+ lines.push('');
+
+ // Emit each tool
+ for (const tool of docs.tools) {
+ lines.push(...generateMCPToolDoc(tool));
+ }
+
+ return lines.join('\n');
+}
+
+export function generateMCPToolDoc(tool: MCPToolDoc): string[] {
+ const lines: string[] = [];
+
+ lines.push(`### ${tool.name}`);
+ lines.push('');
+ lines.push(tool.description);
+ lines.push('');
+
+ const properties = tool.input_schema.properties ?? {};
+ const required = new Set(tool.input_schema.required ?? []);
+ const propertyNames = Object.keys(properties);
+
+ if (propertyNames.length === 0) {
+ lines.push('**Arguments:** none.');
+ lines.push('');
+ } else {
+ lines.push('**Arguments:**');
+ lines.push('');
+ for (const propName of propertyNames) {
+ const prop = properties[propName];
+ const isRequired = required.has(propName);
+ const requiredLabel = isRequired ? 'required' : 'optional';
+ const typeLabel = formatPropertyType(prop);
+ lines.push(`- \`${propName}\` (${typeLabel}, ${requiredLabel}): ${prop.description ?? ''}`);
+ }
+ lines.push('');
+ }
+
+ // Synthesize a minimal JSON example from required params only.
+ // Skip the example entirely when there are no required params (tools
+ // like check_permissions where everything is optional) or when the
+ // required set is empty after filtering — avoid emitting {} for tools
+ // that are only valid with at least one of several mutually-optional groups.
+ const exampleObj: Record<string, unknown> = {};
+ for (const propName of propertyNames) {
+ if (required.has(propName)) {
+ exampleObj[propName] = syntheticExampleValue(propName, properties[propName]);
+ }
+ }
+
+ if (Object.keys(exampleObj).length > 0) {
+ lines.push('```json');
+ lines.push(JSON.stringify(exampleObj));
+ lines.push('```');
+ lines.push('');
+ }
+
+ return lines;
+}
+
+function escapeTableCell(value: string): string {
+ return value.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+function formatPropertyType(prop: MCPPropertyDoc): string {
+ if (prop.type === 'array') {
+ const itemType = prop.items?.type ?? 'unknown';
+ return `array of ${itemType}`;
+ }
+ return prop.type;
+}
+
+function syntheticExampleValue(name: string, prop: MCPPropertyDoc): unknown {
+ switch (prop.type) {
+ case 'integer':
+ if (name === 'pid') return 844;
+ if (name === 'window_id') return 10725;
+ if (name === 'element_index') return 14;
+ if (name === 'x' || name === 'x1' || name === 'x2' || name === 'from_x' || name === 'to_x') return 100;
+ if (name === 'y' || name === 'y1' || name === 'y2' || name === 'from_y' || name === 'to_y') return 200;
+ return 1;
+ case 'number':
+ if (name === 'x' || name === 'x1' || name === 'x2' || name === 'from_x' || name === 'to_x') return 100;
+ if (name === 'y' || name === 'y1' || name === 'y2' || name === 'from_y' || name === 'to_y') return 200;
+ return 0.5;
+ case 'boolean':
+ return false;
+ case 'array':
+ if (name === 'keys') return ['cmd', 'c'];
+ if (name === 'modifiers') return ['cmd'];
+ return [];
+ case 'string':
+ if (name === 'text') return 'hello';
+ if (name === 'key') return 'return';
+ if (name === 'direction') return 'down';
+ if (name === 'action') return 'get_text';
+ if (name === 'bundle_id') return 'com.apple.finder';
+ if (name === 'value') return '42';
+ if (name === 'key_path' || name === 'key') return 'capture_mode';
+ if (name === 'dir' || name === 'output_dir') return '~/cua-trajectories/demo1';
+ return 'example';
+ default:
+ return 'value';
+ }
+}
+
+// ============================================================================
+// Run
+// ============================================================================
+
+main().catch((error) => {
+ console.error('Error:', error);
+ process.exit(1);
+});