CLI Command Reference

Peekaboo’s CLI mirrors everything the agent can do. Commands share the same snapshot cache and most support --json (alias: --json-output) for scripting. Run peekaboo with no arguments to print the root help menu, and peekaboo --version at any time to see the embedded build/commit metadata that Poltergeist stamped into the binary.

Use peekaboo <command> --help for inline flag descriptions; this page links to the authoritative docs in docs/commands/.

#Vision & Capture

• see – Capture annotated UI maps, produce snapshot IDs, and optionally run AI analysis.
• image – Save raw PNG/JPG captures of screens, windows, or menu bar regions; supports --analyze prompts.
• capture – Long-running capture. capture live (adaptive PNG frames) replaces watch; capture video ingests a video and samples frames. Outputs frames, contact sheet, metadata, optional MP4.
• list – Subcommands: apps, windows, screens, menubar, permissions.
• tools – Filter native vs MCP tools; group by server or emit JSON summaries.
• completions – Generate shell-native completions for zsh, bash, and fish from Commander metadata.
• run – Execute .peekaboo.json scripts (--output, --no-fail-fast).
• sleep – Millisecond pauses between steps.
• clean – Remove snapshot caches by ID, age, or all at once (--dry-run supported).
• config – Subcommands: init, show, edit, validate, add, login, set-credential (legacy), add-provider, list-providers, test-provider, remove-provider, models.
• daemon – Start/stop/status for the headless daemon (live window tracking, in-memory snapshots).
• permissions – status (default), grant, and Event Synthesizing request helpers.
• learn – Print the complete agent guide (system prompt, tool catalog, Commander signatures).

#Interaction

• click – Target elements by ID/query/coords with smart waits and focus helpers.
• type – Send text and control keys; supports --clear, --delay, tab counts, etc.
• press – Fire SpecialKey sequences with repeat counts.
• hotkey – Emit modifier combos like cmd,shift,t in one shot.
• paste – Atomically set clipboard → paste (Cmd+V) → restore clipboard.
• scroll – Directional scrolling with optional element targeting and smooth mode.
• swipe – Gesture-style drags between IDs or coordinates (--duration, --steps).
• drag – Drag-and-drop across elements, coordinates, or Dock destinations with modifiers.
• move – Position the cursor at coordinates, element centers, or screen center with optional smoothing.

#Windows, Menus, Apps, Spaces

• window – Subcommands: close, minimize, maximize, move, resize, set-bounds, focus, list.
• space – list, switch, move-window for Spaces/virtual desktops.
• menu – click, click-extra, list, list-all for application menus + menu extras.
• menubar – list and click status-bar icons by name or index.
• app – launch, quit, relaunch, hide, unhide, switch, list; launch now accepts repeatable --open <url|path> arguments (plus --wait-until-ready, --no-focus) to pass documents/URLs directly to the target app.
• open – Enhanced macOS open that respects --app/--bundle-id, --wait-until-ready, --no-focus, and emits JSON payloads for scripting.
• dock – launch, right-click, hide, show, list Dock items.
• dialog – click, input, file, dismiss, list system dialogs.
• visualizer – Run the built-in visual feedback smoke suite (fires screenshot flash, capture HUD, click ripple, menu highlights, etc.) to verify Peekaboo.app overlays.

#Automation & Integrations

• agent – Natural-language automation with dry-run planning, resume, audio modes, and model overrides.
• mcp – serve, list, add, remove, enable, disable, info, test, call, inspect (stub) for Model Context Protocol workflows.

Need structured payloads? Pass --json (or --json-output) where supported, or orchestrate multiple commands inside .peekaboo.json scripts executed via peekaboo run.