Cua Docs

Update Cua Driver

Check whether a newer Cua Driver release is available and install it.

Cua Driver gives you three update paths: a passive banner at launch time, a CLI command that only checks, and a separate command that installs the update. Keep the check and apply steps separate so you can decide when to change the installed binary.

Version numbers, timestamps, and release links in the sample output below are illustrative. Use your command's actual output to identify the installed and available releases; the 0.13.0 migration notes describe that historical upgrade.

Pacman-managed installations#

This behavior requires a build containing the pacman update fix (#3636). It is not included in the 0.24.0 release.

If pacman owns the running Cua Driver executable, use your package repository to update it:

sudo pacman -Syu

Driver does not run this command for you. It skips the upstream update banner and refuses its vendor installer and stable/nightly channel changes. The package repository controls which version is available, including its release-age policy. Having pacman installed alone does not change an independently installed Driver's update behavior. Driver queries /usr/bin/pacman directly, so shell aliases and executables earlier in PATH do not override ownership detection.

For a pacman-owned executable, check-update, update, and update --apply return an unavailable-check result with pacman guidance and a nonzero exit code. The CLI JSON and MCP check_for_update payload keep latest_version, selected_channel, install_command, and release_notes_url as null, set update_available and cache_hit to false, and explain the reason in error. This does not mean that the package is up to date: Driver does not query pacman's repository databases or reuse a cached GitHub release. The source field remains github_releases, identifying the upstream check that was not performed.

channel status and channel set also return pacman guidance and a nonzero exit code. Their JSON output sets selected_channel to null and explains the reason in error. A saved stable/nightly preference is ignored and left unchanged.

The vendor update and channel instructions that follow apply to installations not managed by pacman.

Before updating from 0.12.x to 0.13.0#

The installer command, CLI/MCP connection flow, tool names, and Python and TypeScript SDK constructors remain the same. Two behavior changes require attention:

  1. standard is the promptless practical default for normal observation, input, file, browser, and configuration tools. Attaching to an existing logged-in Chromium profile remains an explicit boundary. Start CLI or MCP with --grant existing-profile, use a matching capability manifest, or supply an authorization host from an embedding application.
  2. The old cursor-style fields and set_agent_cursor_style operation are removed. Sessions use the built-in animated cua.default theme and display the public session name in a badge below the cursor unless an installed theme ID is selected.

For unattended authenticated-browser work, create a short-lived bounded manifest instead of disabling every approval. Use unrestricted only when a trusted launcher explicitly supplies --dangerously-bypass-approvals and the environment can tolerate full Cua autonomy.

See Permission modes and bounded autonomy, Drive a web page, and Personalize the agent cursor before restarting a long-running daemon or worker.

Check for updates#

Checks use the saved channel. Existing installations default to stable. Inspect it with:

cua-driver channel status

To switch to nightly and install that channel's release:

cua-driver channel set nightly
cua-driver update --apply

Changing the channel does not install by itself. A stable/nightly transition is reported as available even when the target version would not compare as newer under ordinary SemVer ordering.

cua-driver check-update

When you're behind:

Current: 0.12.6
Latest:  0.13.0

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

When you're current:

Current: 0.13.0
Latest:  0.13.0

You're on the latest release.

Flags:

  • --json: return a machine-readable payload, shown below.
  • --no-cache: skip the 20-hour on-disk cache and force a fresh GitHub check.

The command exits with 0 when the check succeeds. Read update_available in the JSON payload to learn whether a release is available. Non-zero exit codes mean the check failed, for example because the network was unavailable or parsing failed.

Apply the update#

cua-driver update --apply

Output:

Current version: 0.12.6
Checking for updates…
New version available: 0.13.0
Downloading and installing Cua Driver 0.13.0…
Installed Cua Driver 0.13.0.

update --apply calls the canonical installer script, the same one-line installer used for the first install.

If the daemon was running before the update, restart it so it uses the new binary. Stop it first:

cua-driver stop

The installer may already have stopped the old daemon. If stop reports that it is not running, continue with startup.

Then use your platform's startup command: on macOS, run open -n -g -a CuaDriver --args serve to preserve app-bundle permission attribution; on Windows with autostart enabled, run cua-driver autostart kick; on Linux or Windows without autostart, run cua-driver serve and leave that terminal open. Preserve any non-default permission-mode flags from your original launch.

In a second terminal if serve occupies the first, run cua-driver --version, cua-driver status, and cua-driver call list_apps. Confirm the expected installed version, a running daemon, and access to a known GUI app. See Verify desktop readiness if the daemon cannot reach your desktop.

On Windows with autostart enabled, the Scheduled Task uses the new binary on its next invocation. autostart enable is idempotent, and the task path resolves through the current junction.

Scripted check (CI / agents)#

cua-driver check-update --json
{
  "current_version": "0.12.6",
  "current_channel": "stable",
  "selected_channel": "stable",
  "latest_version": "0.13.0",
  "update_available": true,
  "source": "github_releases",
  "checked_at": "2026-07-01T14:30:00Z",
  "cache_hit": false,
  "install_command": "curl -fsSL https://cua.ai/driver/install.sh | bash",
  "release_notes_url": "https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.13.0",
  "error": null
}

When the installed version is current, install_command and release_notes_url are null.

Use the JSON form from a bash script:

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

The same payload is available over MCP through the check_for_update tool. MCP does not provide an apply variant because installing through MCP would replace the running server process.

Passive banner#

Every cua-driver mcp, serve, and doctor invocation starts a background version check. If it finds a newer release, Cua Driver prints a two-line banner to stderr:

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

The check uses a channel-keyed 20-hour cache and never blocks startup. A cached stable result can never satisfy a nightly check, or vice versa. One-shot commands such as --version, call, and list-tools skip it so piped output remains clean.

Disable the check for one invocation:

CUA_DRIVER_RS_UPDATE_CHECK=false cua-driver serve

Disable it permanently:

cua-driver config set update_check_enabled false