macOS Permissions

The macOS-only `cua-driver permissions` command for inspecting and requesting Accessibility and Screen Recording TCC grants.

cua-driver permissions is a macOS-only command. It is not part of the auto-generated CLI reference because it has no Windows or Linux counterpart, so it is documented here.

cua-driver permissions (macOS)#

Inspect or request the macOS TCC grants the driver needs (Accessibility and Screen Recording). Embedded-mode hosts do not use cua-driver permissions grant; the host app requests these grants itself, as described in Embedding.

The same rule applies to an in-process CuaDriver.create() runtime and to cua-driver mcp --direct: check_permissions is read-only even if a caller passes {"prompt": true}. It reports source.attribution: "host", source.direct_runtime: true, and leaves direct ScreenCaptureKit readiness as not_checked. The responsible host owns permission prompts, Settings navigation, and the restart flow.

cua-driver permissions status   # report grant status; read-only, no prompt
cua-driver permissions grant    # launch CuaDriver via LaunchServices so the prompt attributes to the app

Flags:

The JSON status distinguishes the ordinary Screen Recording preflight from direct ScreenCaptureKit readiness. Because macOS Tahoe can show a separate private-window-picker bypass dialog when ScreenCaptureKit is queried, permissions status never runs that probe: it returns screen_recording_capturable: null and direct_capture_status: "not_checked". This preserves the command's read-only, no-prompt contract. After permissions grant completes a successful live probe, status also returns direct_capture_verification with the permissions_grant source, the UTC verification time, and the macOS bundle ID whose probe succeeded. ScreenCaptureKit confirms that the explicit probe succeeded but does not report whether consent was newly granted or already present. The permission service validates the stored schema, source, timestamp, and bundle ID, and only loads the record when the live status belongs to the driver daemon identity. The CLI only renders the complete live and historical observation. Historical evidence does not turn the read-only status call into a claim about current ScreenCaptureKit readiness.

permissions grant never sends a prompt-capable request over the daemon socket. It launches a short-lived instance of the installed CuaDriver app through LaunchServices, explains the additional dialog before deliberately triggering it, and requires a successful live capture probe. The child returns only content-free grant status through a private temporary file; that file cannot grant permission or widen an agent session. macOS describes the combined privacy category as screen and system-audio recording even though Cua Driver's current ScreenCaptureKit recorder captures screen video only and does not enable audio capture. The consent is limited to macOS capture; it does not authorize browser-profile access, browser data, or CDP attachment.

The LaunchServices-hosted process records successful verification before it returns because that process owns the probed macOS identity. Records are stored separately for the release and local identities and contain the matching bundle ID. A failed explicit probe clears the matching prior record. If the record cannot be written, permissions grant reports the live success but exits with an error instead of claiming that later status calls can corroborate it.

If the installed app is not listed under Screen & System Audio Recording after the prompt, click +, add /Applications/CuaDriver.app (or /Applications/CuaDriverLocal.app for a local build), enable it, and run permissions grant again. This recovers a stale or missing macOS registration without granting the terminal or another build identity.

Automation prompts can also appear when an explicitly requested browser or app operation uses Apple Events. Those grants are target-specific and remain outside the core permissions status payload.

After Accessibility or Screen Recording grants change, fully quit and relaunch the responsible application before recreating its runtime. For standalone service mode that application is CuaDriver.app; for direct SDK or direct MCP mode it is the importing or spawning host.

For the complete prompt sequence in a Lume guest, see Run Cua Driver in a macOS Lume VM. Source-built test seeds also need a stable certificate identity; follow Run Cua Driver macOS tests in a Lume VM.