Automation

`peekaboo press`

Home GitHub Edit page

peekaboo press

press fires individual SpecialKey values (Return, Tab, arrows, F-keys, etc.) in sequence. It routes through the same TypeActionsRequest stack as type, so focus handling and snapshot reuse behave the same way.

#Key options

FlagDescription
[keys…]Positional list of keys (return, tab, up, f1, forward_delete, …). Validation rejects unknown tokens.
--count <n>Repeat the entire key sequence n times (default 1).
--delay <ms>Delay between key presses (default 100).
--hold <ms>Planned hold duration per key (currently stored but not yet wired to the automation layer).
--snapshot <id>Optional snapshot ID used for validation/focus (no implicit “latest snapshot” lookup).
Target flags--app <name>, --pid <pid>, --window-id <id>, --window-title <title>, --window-index <n> — focus a specific app/window before pressing keys. (--window-title/--window-index require --app or --pid; --window-id does not.)
Focus flagsSame FocusCommandOptions bundle as click/type.

#Implementation notes

  • Keys are lowercased and mapped to SpecialKey; the command fails fast with a helpful message if a token isn’t recognized.
  • Focus runs when --snapshot or the target flags are present; for “blind” global shortcuts you can omit both and let the current frontmost app receive the keys.
  • Repetition multiplies the sequence client-side—e.g., press tab return --count 3 becomes six actions—so you get predictable ordering.
  • Results include the literal key list, total presses, repeat count, and elapsed time in both text and JSON modes.
  • The --hold flag is parsed and stored for future use but does not change behavior yet; include manual sleeps if you need long key holds.

#Examples

# Equivalent to hitting Return once
peekaboo press return

# Tab through a menu twice, then confirm
peekaboo press tab tab return

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

#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).
  • Re-run with --json or --verbose to surface detailed errors.