Automation

`peekaboo press`

Home GitHub Edit page

peekaboo press

press sends raw xdotool key-style chords such as cmd+c, cmd+shift+t, and Return. Multiple positional chords form a sequence. Raw keys require either --foreground or an exact window/snapshot receipt whose focused element stays unchanged through native background dispatch.

#Key options

FlagDescription
[chords…]Chords in xdotool syntax. Modifiers are cmd/command, shift, option/alt, ctrl/control, and fn; the non-modifier key comes last.
--count <n>Repeat the entire key sequence n times (default 1).
--delay <duration>Delay between key presses (default 100ms; bare values are milliseconds).
--hold <duration>Hold duration per key (default 50ms; bare values are milliseconds).
--snapshot <id>Optional snapshot ID used for validation/focus (no implicit “latest snapshot” lookup).
Target flagsAn exact window selector enables receipt-pinned background press; app/PID-only targeting still requires --foreground.
--foregroundFocus a supplied target or intentionally send foreground/global key presses.
Focus flagsForeground focus controls; same FocusCommandOptions bundle as click/type.

#Delivery mode

  • Exact background accepts only a fresh exact-window selector or snapshot. Peekaboo pins process generation, window ID/bounds, and focused-element identity; missing, ambiguous, or stale receipts refuse before dispatch. App/PID-only and targetless forms retain the canonical retry-safe refusal.
  • Foreground (--foreground) focuses a supplied target first and sends normal/global key presses. A dispatched chord remains effect: unverifiable; run a fresh observation before continuing.
  • Prefer named Accessibility actions and dedicated menu/window/app/dialog operations in background workflows. Exact-window press exposes the receipt-pinned transport but still reports its semantic effect honestly.

#Implementation notes

  • Bare keys include Return, Tab, Escape, Delete/Forward Delete, arrows, navigation keys, F1-F12, letters/digits, Space, and standard punctuation. Comma- and space-delimited chord syntax is rejected.
  • Background raw chords never collapse an exact selector to process delivery and never silently foreground. Exact-window remote delivery requires Bridge protocol 1.24.
  • Repetition multiplies the sequence client-side—e.g., press tab return --count 3 --foreground becomes six actions—so you get predictable ordering.
  • Results include the literal key list, total presses, repeat count, delivery mode, optional target PID, and elapsed time in both text and JSON modes.
  • The --hold flag is passed to the hotkey service for each key press.

#Examples

# Equivalent to hitting Return once
peekaboo press return --foreground

# Tab through a menu twice, then confirm
peekaboo press Tab Tab Return --foreground

# Walk a dialog down three rows with headroom between repetitions
peekaboo press down --count 3 --delay 200ms --foreground

# Send Return after explicitly focusing TextEdit
peekaboo press return --app TextEdit --foreground

# Reopen a browser tab with explicit foreground consent
peekaboo press cmd+shift+t --app Safari --foreground

# Send a chord to one already-focused exact window without activating it
peekaboo press cmd+l --window-id 12345

#Troubleshooting

  • Verify Screen Recording, Accessibility, and Event Synthesizing permissions (peekaboo permissions status).
  • Confirm your process with peekaboo app list, its exact window with peekaboo window list, and current UI with peekaboo see before rerunning.
  • If you see SNAPSHOT_NOT_FOUND, regenerate the snapshot with peekaboo see.
  • Re-run with --json or --verbose to surface detailed errors.