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: "Automates macOS UI via a CLI: capture screens, inspect and target UI elements, drive mouse and keyboard input, and manage apps, windows, menus, and dialogs."4metadata:5 source: https://skillmd.com/skills/comeonoliver/peekaboo6---7# Peekaboo89Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI10elements, drive input, and manage apps/windows/menus. Commands share a snapshot11cache and support `--json`/`-j` for scripting. Run `peekaboo` or12`peekaboo <cmd> --help` for flags; `peekaboo --version` prints build metadata.13Tip: run via `polter peekaboo` to ensure fresh builds.1415## Features (all CLI capabilities, excluding agent/MCP)1617Core1819- `bridge`: inspect Peekaboo Bridge host connectivity20- `capture`: live capture or video ingest + frame extraction21- `clean`: prune snapshot cache and temp files22- `config`: init/show/edit/validate, providers, models, credentials23- `image`: capture screenshots (screen/window/menu bar regions)24- `learn`: print the full agent guide + tool catalog25- `list`: apps, windows, screens, menubar, permissions26- `permissions`: check Screen Recording/Accessibility status27- `run`: execute `.peekaboo.json` scripts28- `sleep`: pause execution for a duration29- `tools`: list available tools with filtering/display options3031Interaction3233- `click`: target by ID/query/coords with smart waits34- `drag`: drag & drop across elements/coords/Dock35- `hotkey`: modifier combos like `cmd,shift,t`36- `move`: cursor positioning with optional smoothing37- `paste`: set clipboard -> paste -> restore38- `press`: special-key sequences with repeats39- `scroll`: directional scrolling (targeted + smooth)40- `swipe`: gesture-style drags between targets41- `type`: text + control keys (`--clear`, delays)4243System4445- `app`: launch/quit/relaunch/hide/unhide/switch/list apps46- `clipboard`: read/write clipboard (text/images/files)47- `dialog`: click/input/file/dismiss/list system dialogs48- `dock`: launch/right-click/hide/show/list Dock items49- `menu`: click/list application menus + menu extras50- `menubar`: list/click status bar items51- `open`: enhanced `open` with app targeting + JSON payloads52- `space`: list/switch/move-window (Spaces)53- `visualizer`: exercise Peekaboo visual feedback animations54- `window`: close/minimize/maximize/move/resize/focus/list5556Vision5758- `see`: annotated UI maps, snapshot IDs, optional analysis5960Global runtime flags6162- `--json`/`-j`, `--verbose`/`-v`, `--log-level <level>`63- `--no-remote`, `--bridge-socket <path>`6465## Quickstart (happy path)6667```bash68peekaboo permissions69peekaboo list apps --json70peekaboo see --annotate --path /tmp/peekaboo-see.png71peekaboo click --on B172peekaboo type "Hello" --return73```7475## Common targeting parameters (most interaction commands)7677- App/window: `--app`, `--pid`, `--window-title`, `--window-id`, `--window-index`78- Snapshot targeting: `--snapshot` (ID from `see`; defaults to latest)79- Element/coords: `--on`/`--id` (element ID), `--coords x,y`80- Focus control: `--no-auto-focus`, `--space-switch`, `--bring-to-current-space`,81 `--focus-timeout-seconds`, `--focus-retry-count`8283## Common capture parameters8485- Output: `--path`, `--format png|jpg`, `--retina`86- Targeting: `--mode screen|window|frontmost`, `--screen-index`,87 `--window-title`, `--window-id`88- Analysis: `--analyze "prompt"`, `--annotate`89- Capture engine: `--capture-engine auto|classic|cg|modern|sckit`9091## Common motion/typing parameters9293- Timing: `--duration` (drag/swipe), `--steps`, `--delay` (type/scroll/press)94- Human-ish movement: `--profile human|linear`, `--wpm` (typing)95- Scroll: `--direction up|down|left|right`, `--amount <ticks>`, `--smooth`9697## Examples9899### See -> click -> type (most reliable flow)100101```bash102peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png103peekaboo click --on B3 --app Safari104peekaboo type "user@example.com" --app Safari105peekaboo press tab --count 1 --app Safari106peekaboo type "supersecret" --app Safari --return107```108109### Target by window id110111```bash112peekaboo list windows --app "Visual Studio Code" --json113peekaboo click --window-id 12345 --coords 120,160114peekaboo type "Hello from Peekaboo" --window-id 12345115```116117### Capture screenshots + analyze118119```bash120peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png121peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"122peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"123```124125### Live capture (motion-aware)126127```bash128peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \129 --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture130```131132### App + window management133134```bash135peekaboo app launch "Safari" --open https://example.com136peekaboo window focus --app Safari --window-title "Example"137peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800138peekaboo app quit --app Safari139```140141### Menus, menubar, dock142143```bash144peekaboo menu click --app Safari --item "New Window"145peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"146peekaboo menu click-extra --title "WiFi"147peekaboo dock launch Safari148peekaboo menubar list --json149```150151### Mouse + gesture input152153```bash154peekaboo move 500,300 --smooth155peekaboo drag --from B1 --to T2156peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800157peekaboo scroll --direction down --amount 6 --smooth158```159160### Keyboard input161162```bash163peekaboo hotkey --keys "cmd,shift,t"164peekaboo press escape165peekaboo type "Line 1\nLine 2" --delay 10166```167168Notes169170- Requires Screen Recording + Accessibility permissions.171- Use `peekaboo see --annotate` to identify targets before clicking.