Updating

Cua Driver ships three update surfaces, all reading from the same GitHub releases endpoint and 20-hour on-disk cache:

check-update and check_for_update are read-only — they never modify your install. Apply is a separate step on purpose.

The launch-time banner

Every cua-driver mcp / cua-driver serve / cua-driver doctor invocation kicks off a non-blocking GitHub poll. If a strictly-newer release is found and you haven't dismissed it, a two-line banner lands on stderr (gh-CLI style):

✨ cua-driver v0.3.2 is available (you have v0.3.1).
   Update with: cua-driver update
   Release notes: https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2

The check is cached for 20 hours, runs on a background task, and never blocks startup. To disable it set CUA_DRIVER_RS_UPDATE_CHECK=false in the environment, or persist the choice with:

cua-driver config set update_check_enabled false

cua-driver check-update — human path

A pure check, never installs. Prints a short summary and exits.

$ cua-driver check-update
Current: 0.3.1
Latest:  0.3.2

Update available. Run `cua-driver update --apply` to install.
Release notes: https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2

When you're on the latest release:

$ cua-driver check-update
Current: 0.3.1
Latest:  0.3.1

You're on the latest release.

Flags

• --json — emit a machine-readable JSON payload (see below).
• --no-cache — skip the 20h on-disk cache and force a fresh GitHub round-trip. Useful when iterating right after a release.

Exit codes

• 0 — the check itself succeeded. The update_available field in the JSON payload carries the "is it outdated?" signal.
• 1 — the check failed (network down, GitHub 5xx, parse error). The text path prints a one-line reason; the JSON path puts it in the error field.

The non-zero-on-outdated convention (à la brew outdated) is intentionally not used — it conflicts with every shell script's "non-zero means error" assumption. Hermes parses JSON; humans read text; the signal lives in the payload.

cua-driver check-update --json — scripted path

Same check, JSON output. Use this when wiring Cua Driver updates into Hermes, CI, or any wrapper script.

$ cua-driver check-update --json
{
  "current_version": "0.3.1",
  "latest_version": "0.3.2",
  "update_available": true,
  "source": "github_releases",
  "checked_at": "2026-05-27T14:30:00Z",
  "cache_hit": false,
  "install_command": "curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash",
  "release_notes_url": "https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2",
  "error": null
}

When you're up to date, install_command and release_notes_url are null:

$ cua-driver check-update --json
{
  "current_version": "0.3.1",
  "latest_version": "0.3.1",
  "update_available": false,
  "source": "github_releases",
  "checked_at": "2026-05-27T14:30:00Z",
  "cache_hit": true,
  "install_command": null,
  "release_notes_url": null,
  "error": null
}

JSON schema

Example consumer snippet (bash)

if cua-driver check-update --json | jq -e '.update_available' > /dev/null; then
    echo "Cua Driver is outdated — applying update"
    cua-driver update --apply
fi

check_for_update — MCP tool

Same payload, surfaced over MCP so agents can probe without spawning a subprocess. Input schema is empty.

$ cua-driver call check_for_update '{}'
{
  "current_version": "0.3.1",
  "latest_version": "0.3.2",
  "update_available": true,
  "source": "github_releases",
  "checked_at": "2026-05-27T14:30:00Z",
  "cache_hit": false,
  "install_command": "curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash",
  "release_notes_url": "https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2",
  "error": null
}

The tool is registered as read_only, idempotent, and open_world (the network can change the answer between calls). MCP clients see both a human summary in content[0].text and the JSON above in structuredContent.

cua-driver update --apply — installing

When you're ready to install, update --apply delegates to the canonical installer script (the same one the docs print as the one-liner):

$ cua-driver update --apply
Current version: 0.3.1
Checking for updates…
New version available: 0.3.2
Downloading and installing Cua Driver 0.3.2…
Installed Cua Driver 0.3.2.

If a daemon was already running, restart it to pick up the new binary:

cua-driver stop && cua-driver serve

update (without --apply) keeps the existing "check + suggest" text behaviour intact for backward compat. Add --json to either form for a structured payload — handy when the calling script wants to log the version it just installed.

$ cua-driver update --json | jq '.update_available'
true