cli-command-reference.md

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

CLI Command Reference

This source-tree reference covers all 33 root commands in the upcoming v4 registry and is checked against the built binary's --help output. Use peekaboo <command> --help for every option and peekaboo tools for the separate MCP/agent tool catalog.

Core commands

Command	Purpose / subcommands
bridge	Inspect Bridge connectivity; status is the default subcommand.
capture	action, live, and video capture workflows.
clean	Remove snapshot cache data, with --dry-run support.
completions	Generate zsh, bash, or fish completion scripts.
config	Configuration plus credential and provider subcommand trees.
daemon	run, start, status, and stop the headless daemon.
learn	Print the agent guide, tool catalog, and live command signatures.
permissions	status, grant, or request <kind>.
screen	list connected displays.
tools	list MCP tools or describe <name> for one schema.

Interaction commands

Command	Purpose
action	Invoke a named accessibility action.
click	Click an element/query or --at x,y.
drag	Drag between element IDs or coordinates using --from and --to.
move	Move the physical pointer to --on or --at.
paste	Paste current clipboard content or atomically set, paste, and restore.
press	Press xdotool-style chords or chord sequences.
scroll	Scroll by direction, optionally on an element.
set-value	Set an accessibility element value directly.
type	Type text; standalone keys and chords belong to press.

System commands

Command	Purpose / subcommands
app	focus, hide, launch, list, quit, relaunch, switch, and unhide.
clipboard	get, set, clear, save, and restore.
dialog	click, dismiss, file, input, and list.
dock	hide, launch, list, right-click, and show.
menu	click or list application menus.
menubar	click or list menu-bar status items.
space	list, move-window, and switch Spaces.
visualizer	Exercise the agent cursor, input HUD, and capture indicators.
window	close, focus, list, maximize, minimize, move, resize, restore, and set-bounds.

Vision, AI, and MCP commands

Command	Purpose / subcommands
see	Capture pixels and element maps; use --tree, --no-screenshot, or --no-elements to select the observation shape.
verify	Poll stable window/element predicates; results are satisfied, unsatisfied, or unknown.
agent	run, resume, sessions, and chat; run is the default.
browser	Control Chrome page content through the browser MCP tool.
mcp	Start the MCP server; serve is the default subcommand.

Shared grammar

Durations accept bare milliseconds, ms, or s: 500, 500ms, 2s, and 1.5s are equivalent forms. Coordinate input is --at x,y; with an app/window target it is target-relative unless --global is present. Modifier lists use comma-separated values such as cmd,shift.

Interaction commands share foreground/focus controls where relevant. Background delivery is the default when Peekaboo can resolve an exact process target; physical pointer gestures and intentional global input require --foreground.

JSON result envelope

Pass --json (or the Commander-provided --json-output alias) for one stable result shape. Every response has success, data (null when unavailable), optional error, and debug_logs. Failed responses exit nonzero and include error.code, error.message, and an actionable error.hint when the command already knows the next step.

Once the command path identifies an action request, its result also includes a top-level effect: confirmed when existing AX/readback verification proves the result, partial for a partly completed multi-step action, unverifiable when input was dispatched without an application-level signal, suspected_noop when a post-check found no change, or refused when a safety gate prevented dispatch. Commander parse/bind failures for recognized action commands report effect: refused; read-only commands omit effect. MCP action tools expose the same canonical fields in result metadata.

When an interaction, window mutation, or application lifecycle command returns a native action receipt, JSON also includes a top-level outcome object. This includes click, type, scroll, press, action, set-value, background window geometry/lifecycle operations, and application launch, relaunch, quit, hide, unhide, focus, and switch. The object is the validated canonical projection: state, route, delivery, evidence, dispatch state/count, retry safety, escalation, refusal reason, and the derived mutation_dispatched, retry_safe, and requires_fresh_observation compatibility fields. The legacy top-level effect and failure safety fields derive from that same object. Read-only commands, older hosts, and actions without native receipts omit outcome rather than fabricating a receipt.