Peekaboo
Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI
elements, drive input, and manage apps/windows/menus. Commands share a snapshot
cache and support --json/-j for scripting. Run peekaboo or
peekaboo <cmd> --help for flags; peekaboo --version prints build metadata.
Tip: run via polter peekaboo to ensure fresh builds.
Features (all CLI capabilities, excluding agent/MCP)
Core
bridge: inspect Peekaboo Bridge host connectivity
capture: live capture or video ingest + frame extraction
clean: prune snapshot cache and temp files
config: init/show/edit/validate, providers, models, credentials
image: capture screenshots (screen/window/menu bar regions)
learn: print the full agent guide + tool catalog
list: apps, windows, screens, menubar, permissions
permissions: check Screen Recording/Accessibility status
run: execute .peekaboo.json scripts
sleep: pause execution for a duration
tools: list available tools with filtering/display options
Interaction
click: target by ID/query/coords with smart waits
drag: drag & drop across elements/coords/Dock
hotkey: modifier combos like cmd,shift,t
move: cursor positioning with optional smoothing
paste: set clipboard -> paste -> restore
press: special-key sequences with repeats
scroll: directional scrolling (targeted + smooth)
swipe: gesture-style drags between targets
type: text + control keys (--clear, delays)
System
app: launch/quit/relaunch/hide/unhide/switch/list apps
clipboard: read/write clipboard (text/images/files)
dialog: click/input/file/dismiss/list system dialogs
dock: launch/right-click/hide/show/list Dock items
menu: click/list application menus + menu extras
menubar: list/click status bar items
open: enhanced open with app targeting + JSON payloads
space: list/switch/move-window (Spaces)
visualizer: exercise Peekaboo visual feedback animations
window: close/minimize/maximize/move/resize/focus/list
Vision
see: annotated UI maps, snapshot IDs, optional analysis
Global runtime flags
--json/-j, --verbose/-v, --log-level <level>
--no-remote, --bridge-socket <path>
Quickstart (happy path)
peekaboo permissions
peekaboo list apps --json
peekaboo see --annotate --path /tmp/peekaboo-see.png
peekaboo click --on B1
peekaboo type "Hello" --return
Common targeting parameters (most interaction commands)
- App/window:
--app, --pid, --window-title, --window-id, --window-index
- Snapshot targeting:
--snapshot (ID from see; defaults to latest)
- Element/coords:
--on/--id (element ID), --coords x,y
- Focus control:
--no-auto-focus, --space-switch, --bring-to-current-space,
--focus-timeout-seconds, --focus-retry-count
Common capture parameters
- Output:
--path, --format png|jpg, --retina
- Targeting:
--mode screen|window|frontmost, --screen-index,
--window-title, --window-id
- Analysis:
--analyze "prompt", --annotate
- Capture engine:
--capture-engine auto|classic|cg|modern|sckit
Common motion/typing parameters
- Timing:
--duration (drag/swipe), --steps, --delay (type/scroll/press)
- Human-ish movement:
--profile human|linear, --wpm (typing)
- Scroll:
--direction up|down|left|right, --amount <ticks>, --smooth
Examples
See -> click -> type (most reliable flow)
peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari
peekaboo press tab --count 1 --app Safari
peekaboo type "supersecret" --app Safari --return
Target by window id
peekaboo list windows --app "Visual Studio Code" --json
peekaboo click --window-id 12345 --coords 120,160
peekaboo type "Hello from Peekaboo" --window-id 12345
Capture screenshots + analyze
peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"
Live capture (motion-aware)
peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
--active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture
App + window management
peekaboo app launch "Safari" --open https://example.com
peekaboo window focus --app Safari --window-title "Example"
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
peekaboo app quit --app Safari
Menus, menubar, dock
peekaboo menu click --app Safari --item "New Window"
peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
peekaboo menu click-extra --title "WiFi"
peekaboo dock launch Safari
peekaboo menubar list --json
Mouse + gesture input
peekaboo move 500,300 --smooth
peekaboo drag --from B1 --to T2
peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
peekaboo scroll --direction down --amount 6 --smooth
Keyboard input
peekaboo hotkey --keys "cmd,shift,t"
peekaboo press escape
peekaboo type "Line 1\nLine 2" --delay 10
Notes
- Requires Screen Recording + Accessibility permissions.
- Use
peekaboo see --annotate to identify targets before clicking.
1---2name: peekaboo3description: Capture and automate macOS UI with the Peekaboo CLI.4homepage: https://peekaboo.boo5origin:6 source: openclaw7 url: https://github.com/openclaw/openclaw8 version: 90eb5b073f9metadata:10 source: https://skillmd.com/skills/moltis-org/peekaboo11---1213# Peekaboo1415Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI16elements, drive input, and manage apps/windows/menus. Commands share a snapshot17cache and support `--json`/`-j` for scripting. Run `peekaboo` or18`peekaboo <cmd> --help` for flags; `peekaboo --version` prints build metadata.19Tip: run via `polter peekaboo` to ensure fresh builds.2021## Features (all CLI capabilities, excluding agent/MCP)2223Core2425- `bridge`: inspect Peekaboo Bridge host connectivity26- `capture`: live capture or video ingest + frame extraction27- `clean`: prune snapshot cache and temp files28- `config`: init/show/edit/validate, providers, models, credentials29- `image`: capture screenshots (screen/window/menu bar regions)30- `learn`: print the full agent guide + tool catalog31- `list`: apps, windows, screens, menubar, permissions32- `permissions`: check Screen Recording/Accessibility status33- `run`: execute `.peekaboo.json` scripts34- `sleep`: pause execution for a duration35- `tools`: list available tools with filtering/display options3637Interaction3839- `click`: target by ID/query/coords with smart waits40- `drag`: drag & drop across elements/coords/Dock41- `hotkey`: modifier combos like `cmd,shift,t`42- `move`: cursor positioning with optional smoothing43- `paste`: set clipboard -> paste -> restore44- `press`: special-key sequences with repeats45- `scroll`: directional scrolling (targeted + smooth)46- `swipe`: gesture-style drags between targets47- `type`: text + control keys (`--clear`, delays)4849System5051- `app`: launch/quit/relaunch/hide/unhide/switch/list apps52- `clipboard`: read/write clipboard (text/images/files)53- `dialog`: click/input/file/dismiss/list system dialogs54- `dock`: launch/right-click/hide/show/list Dock items55- `menu`: click/list application menus + menu extras56- `menubar`: list/click status bar items57- `open`: enhanced `open` with app targeting + JSON payloads58- `space`: list/switch/move-window (Spaces)59- `visualizer`: exercise Peekaboo visual feedback animations60- `window`: close/minimize/maximize/move/resize/focus/list6162Vision6364- `see`: annotated UI maps, snapshot IDs, optional analysis6566Global runtime flags6768- `--json`/`-j`, `--verbose`/`-v`, `--log-level <level>`69- `--no-remote`, `--bridge-socket <path>`7071## Quickstart (happy path)7273```bash74peekaboo permissions75peekaboo list apps --json76peekaboo see --annotate --path /tmp/peekaboo-see.png77peekaboo click --on B178peekaboo type "Hello" --return79```8081## Common targeting parameters (most interaction commands)8283- App/window: `--app`, `--pid`, `--window-title`, `--window-id`, `--window-index`84- Snapshot targeting: `--snapshot` (ID from `see`; defaults to latest)85- Element/coords: `--on`/`--id` (element ID), `--coords x,y`86- Focus control: `--no-auto-focus`, `--space-switch`, `--bring-to-current-space`,87 `--focus-timeout-seconds`, `--focus-retry-count`8889## Common capture parameters9091- Output: `--path`, `--format png|jpg`, `--retina`92- Targeting: `--mode screen|window|frontmost`, `--screen-index`,93 `--window-title`, `--window-id`94- Analysis: `--analyze "prompt"`, `--annotate`95- Capture engine: `--capture-engine auto|classic|cg|modern|sckit`9697## Common motion/typing parameters9899- Timing: `--duration` (drag/swipe), `--steps`, `--delay` (type/scroll/press)100- Human-ish movement: `--profile human|linear`, `--wpm` (typing)101- Scroll: `--direction up|down|left|right`, `--amount <ticks>`, `--smooth`102103## Examples104105### See -> click -> type (most reliable flow)106107```bash108peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png109peekaboo click --on B3 --app Safari110peekaboo type "user@example.com" --app Safari111peekaboo press tab --count 1 --app Safari112peekaboo type "supersecret" --app Safari --return113```114115### Target by window id116117```bash118peekaboo list windows --app "Visual Studio Code" --json119peekaboo click --window-id 12345 --coords 120,160120peekaboo type "Hello from Peekaboo" --window-id 12345121```122123### Capture screenshots + analyze124125```bash126peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png127peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"128peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"129```130131### Live capture (motion-aware)132133```bash134peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \135 --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture136```137138### App + window management139140```bash141peekaboo app launch "Safari" --open https://example.com142peekaboo window focus --app Safari --window-title "Example"143peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800144peekaboo app quit --app Safari145```146147### Menus, menubar, dock148149```bash150peekaboo menu click --app Safari --item "New Window"151peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"152peekaboo menu click-extra --title "WiFi"153peekaboo dock launch Safari154peekaboo menubar list --json155```156157### Mouse + gesture input158159```bash160peekaboo move 500,300 --smooth161peekaboo drag --from B1 --to T2162peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800163peekaboo scroll --direction down --amount 6 --smooth164```165166### Keyboard input167168```bash169peekaboo hotkey --keys "cmd,shift,t"170peekaboo press escape171peekaboo type "Line 1\nLine 2" --delay 10172```173174Notes175176- Requires Screen Recording + Accessibility permissions.177- Use `peekaboo see --annotate` to identify targets before clicking.