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.

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.

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.