Automate the macOS UI with the Peekaboo CLI

How to use

The examples use v4 syntax, which removed old command roots: see has replaced the screenshot command, image capture without element detection has its own mode, clicks use the press command with chords, and window and menu management moved to the see command. For a removed-command error, use the replacement named by the installed CLI. For host or permission failures, inspect the bridge status and its JSON output for the selected host. For targeting failures, read the leaf help and obtain fresh UI state with a new see command. On macOS 15+, the private window picker prompt is separate from the base Screen Recording grant and can appear even when Bridge permissions are correct.

Check the current documentation and the installed command's help; for older versions, follow that version's help.

V4 removed the old command roots listed in the migration table.

V4 replaced the old screenshot, click, and window-management roots with the new see, press, and related commands; for pixels without element detection use the screen mode, and for clicks use chords such as cmd+shift+t.

For a removed-command error, use the replacement named by the installed CLI.

For host or permission failures, inspect the bridge status output.

Check the JSON status output for the selected host.

For targeting failures, read the leaf help and obtain fresh UI state with a new see command.

On macOS 15+, the private window picker prompt is separate from the base Screen Recording grant.

The window picker prompt can appear even when Bridge permissions are correct.

The OpenClaw macOS app hosts Peekaboo Bridge when Computer Control is enabled, its provider is Peekaboo, and Peekaboo Bridge is enabled.

Keep the existing OpenClaw socket selection when running through that host.

export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"
peekaboo bridge status --json

Confirm that the selected host and socket are the intended ones, and preserve any explicit host or socket selection. If the required host is unavailable, report that outcome; do not clear the selection or switch Computer Control providers to make a command succeed.

Permissions belong to the process or Bridge host performing the operation, so do not pass the permission override flag unless the caller has the required permissions.

Use each command's help to learn its flags and targeting requirements instead of copying a flag between commands.

Use root help to discover the available commands and leaf help for the flags and targeting requirements of a specific command.

peekaboo --help
peekaboo app list --help
peekaboo see --help
peekaboo press --help
peekaboo drag --help

For other operations, including clicking, typing, scrolling, and managing windows or menus, use the matching leaf command, put command options after it, and use the structured-output flag to request structured output.

Start with an application inventory and a fresh view of the target before acting.

List the running applications and capture a fresh, annotated view of the intended app and window.

peekaboo app list --json
peekaboo see --app Safari --window-title "Example" --annotate \
  --path /tmp/peekaboo-example.png --json

Read the returned elements before acting. Keep actions tied to the intended app, window, and fresh snapshot, and do not reuse example element IDs. After an action, inspect the UI again and check the requested result, refreshing the observation when the window changes or a target becomes stale.

For a screenshot without element detection, capture the screen in screen mode with element detection disabled.

peekaboo see --mode screen --screen-index 0 --no-elements --retina \
  --path /tmp/peekaboo-screen.png --json

Raw keyboard chords require explicit foreground interaction or a fresh exact-window receipt accepted by the press command. Dragging always moves the shared cursor and requires the foreground flag, so use these only when foreground interaction is authorized.

peekaboo press cmd+shift+t --app Safari --foreground --json
peekaboo drag --from 100,500 --to 100,200 --duration 800ms --foreground --json

Use the actual target and coordinates from the current observation, prefer explicit duration units for timed actions, and consult each command's help for its options and prerequisites.