Automation

`peekaboo click`

Home GitHub Edit page

peekaboo click

click is the primary interaction command. It accepts element IDs, fuzzy text queries, or literal coordinates and then drives AutomationServiceBridge.click with built-in focus handling and wait logic.

#Key options

FlagDescription
[query]Optional positional text query (case-insensitive substring match).
--on <id> / --id <id>Target a specific Peekaboo element ID (e.g., B1, T2).
--coords x,yClick exact coordinates without touching the snapshot cache.
--snapshot <id>Reuse a prior snapshot; defaults to services.snapshots.getMostRecentSnapshot() when omitted.
Target flags--app <name>, --pid <pid>, --window-id <id>, --window-title <title>, --window-index <n> — focus a specific app/window before clicking. (--window-title/--window-index require --app or --pid; --window-id does not.)
--wait-for <ms>Millisecond timeout while waiting for the element to appear (default 5000).
--double / --rightPerform double-click or secondary-click instead of the default single click.
Focus flags--no-auto-focus, --focus-timeout-seconds, --focus-retry-count, --space-switch, --bring-to-current-space (see FocusCommandOptions).

#Implementation notes

  • Validation makes sure you only provide one targeting strategy (ID/query vs. --coords) and that coordinate strings parse cleanly into doubles.
  • When no --snapshot is provided, the command grabs the most recent snapshot ID (if any) before waiting for elements. Coordinate clicks skip snapshot usage entirely to avoid stale caches.
  • Element-based clicks call AutomationServiceBridge.waitForElement with the supplied timeout so you don’t have to insert manual sleeps. Helpful hints are printed when timeouts expire.
  • Focus is enforced just before the click by ensureFocused; by default it will hop Spaces if necessary unless you pass --no-auto-focus.
  • JSON output reports clickedElement, the resolved coordinates, wait time, execution time, the frontmost app after the click, and targetPoint diagnostics for element/query targets. targetPoint includes the original snapshot midpoint, the final resolved point, the snapshot ID, and whether a moved-window adjustment was applied.

#Examples

# Click the "Send" button (ID from a previous `see` run)
peekaboo click --on B12

# Fuzzy search + extra wait for a slow dialog
peekaboo click "Allow" --wait-for 8000 --space-switch

# Issue a right-click at raw coordinates
peekaboo click --coords 1024,88 --right --no-auto-focus

#Troubleshooting

  • Verify Screen Recording + Accessibility permissions (peekaboo permissions status).
  • Confirm your target (app/window/selector) with peekaboo list/peekaboo see before rerunning.
  • If you see SNAPSHOT_NOT_FOUND, regenerate the snapshot with peekaboo see (or omit --snapshot to use the most recent one). Cleaned/expired snapshots cannot be reused.
  • Re-run with --json or --verbose to surface detailed errors.