Peekaboo/docs/cli-command-reference.md

summary	read_when
Cheat sheet for every Peekaboo CLI command grouped by category.	learning what each CLI subcommand does mapping agent tools to direct CLI usage

CLI Command Reference

Peekaboo’s CLI mirrors everything the agent can do. Commands share the same session cache and most support --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 session IDs, and optionally run AI analysis.
• image – Save raw PNG/JPG captures of screens, windows, or menu bar regions; supports --analyze prompts.
• list – Subcommands: apps, windows, screens, menubar, permissions.
• tools – Filter native vs MCP tools; group by server or emit JSON summaries.
• run – Execute .peekaboo.json scripts (--output, --no-fail-fast).
• sleep – Millisecond pauses between steps.
• clean – Remove session caches by ID, age, or all at once (--dry-run supported).
• config – Subcommands: init, show, edit, validate, set-credential, add-provider, list-providers, test-provider, remove-provider, models.
• permissions – status (default) and grant helpers for Screen Recording/Accessibility.
• 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.
• 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.

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-output (where supported) or orchestrate multiple commands inside .peekaboo.json scripts executed via peekaboo run.