Report macctl's health: TCC permission status (Accessibility, Screen Recording, Full Disk Access), native helper reachability, active permission profile/tiers, audit log location, and version info. Always available regardless of profile. Use this first when other tools fail with PERMISSION_MISSING or HELPER_UNAVAILABLE.

List connected displays with their frame, visible frame, backing scale factor, and which one is main. No permission required.

Take a screenshot of a full display (main display by default). Requires Screen Recording permission; falls back to the screencapture CLI if the native helper is unavailable.

Take a screenshot of a rectangular region in global screen points (top-left origin). Requires Screen Recording permission; falls back to screencapture -R if the helper is unavailable.

Take a screenshot of a single window, identified by the windowHandle from list_capturable_windows. Requires Screen Recording permission; falls back to screencapture -l if the helper is unavailable (the raw windowId embedded in the handle is reused directly, so this still works in fallback mode).

List on-screen windows available for capture_window, via ScreenCaptureKit: windowId (pass directly as capture_window's windowHandle), title, frame, owning app name/bundle id/pid. Requires Screen Recording permission.

List all on-screen windows: title, owning app, pid, bounds, layer, minimized state, and an opaque windowHandle to pass to window_focus/window_set_state/window_move/window_close. Requires Accessibility permission.

Get the frontmost application and its focused window, with a windowHandle for follow-up calls. Requires Accessibility permission.

Get screen layout (frames, visible frames, scale factors), system light/dark appearance, and current cursor position. No permission required.

Activate a window's owning app and raise the window. Requires Accessibility permission.

Change a window's state: minimize, restore, maximize, fullscreen, hide (owning app), or show (owning app). Requires Accessibility permission.

Move and/or resize a window. Position/size are set independently — pass only x+y, only width+height, or both. Returns the verified final frame (apps may clamp requested geometry). Requires Accessibility permission.

Close a window by pressing its AXCloseButton. Destructive — unsaved changes in the window may be lost. Requires Accessibility permission.

Move the mouse cursor to a global screen point (top-left origin, points not pixels). Requires Accessibility permission.

Click the mouse at a global screen point. Supports left/right/middle button and single/double/triple click count. Requires Accessibility permission.

Press the mouse button at one point, drag through interpolated intermediate points, and release at another. Requires Accessibility permission.

Post a scroll-wheel event, optionally moving the cursor to a point first. Positive deltaY scrolls up/content-down per system convention. Requires Accessibility permission.

Type Unicode text at the current keyboard focus, layout-independent. Short text is synthesized character-by-character; text over ~200 characters is typed via a clipboard paste (the prior clipboard contents are restored afterward). Requires Accessibility permission.

Press a keyboard chord, e.g. "cmd+shift+4", "cmd+c", "return", "left". Modifiers: cmd, shift, alt/option, ctrl, fn. Requires Accessibility permission.

Hold a single key down (action: down) or release it (action: up), for gesture-like sequences (e.g. holding shift while clicking multiple items). Held keys auto-release after 30s as a safety net, and on helper shutdown. Requires Accessibility permission.

Walk the accessibility (AXUIElement) tree of an app or a specific window, returning role/title/value/description/identifier/enabled/frame per node plus an elementHandle usable with ax_invoke/ax_set_value. Depth- and node-count-capped. Requires Accessibility permission.

Bounded breadth-first search over an app's (or one window's) accessibility tree for elements matching role, a case-insensitive title/value substring, and/or an AXIdentifier. Returns elementHandles for ax_invoke/ax_set_value. Requires Accessibility permission.

Perform an accessibility action on an element (default "AXPress", i.e. click/activate). Use the action names reported when an invalid action is requested to discover what's available. Requires Accessibility permission.

Set an element's AXValue directly if settable; otherwise falls back to focusing the element, selecting all (Cmd+A), and typing the replacement text. Reports whether the final read-back value matches what was requested. Requires Accessibility permission.

Report CPU, memory, disk, network, battery, and graphics info (via systeminformation), plus macOS version (sw_vers), raw hardware sysctls, and the hardware model (system_profiler SPHardwareDataType). No permission required.

List launchd services: running processes (launchctl list) joined with installed LaunchAgents/LaunchDaemons plists under ~/Library/LaunchAgents, /Library/LaunchAgents, and /Library/LaunchDaemons. No permission required.

List installed applications: name, bundle id, version, path. Fast path: mdfind app-bundle query + Info.plist (falls back to a plain directory scan of /Applications if mdfind returns nothing). thorough:true instead uses system_profiler SPApplicationsDataType (slower, includes code-signing/obtained-from info). No permission required.

List running processes (pid, ppid, cpu%, mem%, rss KB, elapsed time, command) via ps. Set enrich:true to additionally cross-reference systeminformation.processes() for user/state/started/path — slower. No permission required.

List well-known macOS folders (home, Desktop, Documents, Downloads, Pictures, Music, Movies, Applications, Library, tmp, and iCloud Drive if present) with their resolved path, whether they exist, and whether they fall within the currently allowed paths (MACCTL_ALLOWED_PATHS). No permission required.

List a directory's entries: name, type, size, modification time. Optionally recursive with a depth cap. Path is checked against MACCTL_ALLOWED_PATHS/MACCTL_DENIED_PATHS.

Read a file's contents as utf8 text or base64 (for binary data), capped at maxBytes. Path is checked against MACCTL_ALLOWED_PATHS/MACCTL_DENIED_PATHS.

Recursively search a directory for files/directories matching a glob name pattern (*/? wildcards) and/or a content regex (text files only, size-capped). Set useMdfind:true to accelerate via Spotlight (mdfind -onlyin, requires an mdfindQuery) instead of walking the tree. Path is checked against MACCTL_ALLOWED_PATHS/MACCTL_DENIED_PATHS. Results are capped.

Write, append to, or create a text/base64-encoded file. Destructive — requires confirm: true when MACCTL_CONFIRM_DESTRUCTIVE is enabled (the default), for every mode (this framework gates confirmation per-tool rather than per-call, so 'create'/'append' are covered by the same gate as an overwrite). Path is checked against MACCTL_ALLOWED_PATHS/MACCTL_DENIED_PATHS. Parent directories are created as needed.

Copy, move, delete a file/directory, or create a directory (mkdir -p semantics). Destructive — requires confirm: true when MACCTL_CONFIRM_DESTRUCTIVE is enabled (the default), for every operation including copy/mkdir (this framework gates confirmation per-tool rather than per-operation, so the safer superset is applied uniformly rather than only for delete). All paths are checked against MACCTL_ALLOWED_PATHS/MACCTL_DENIED_PATHS.

Read the current contents of the system clipboard: text, file references, and whether an image is present. Uses the native helper (NSPasteboard); falls back to pbpaste (text only) if the helper is unavailable. No permission required.

Replace the system clipboard contents with text, or with file references (native helper only — no CLI fallback exists for file references). Uses the native helper (NSPasteboard); falls back to pbcopy (text only) if the helper is unavailable. Overwrites whatever is currently on the clipboard. No permission required.