Skip to content

Latest commit

 

History

History
47 lines (38 loc) · 2.81 KB

hotkey.md

File metadata and controls

47 lines (38 loc) · 2.81 KB
summary read_when
Send modifier combos via peekaboo hotkey
triggering Cmd-based shortcuts without scripting AppleScript
validating that focus handling works before firing global hotkeys

peekaboo hotkey

hotkey presses multiple keys at once (Cmd+C, Cmd+Shift+T, etc.). It accepts comma- or space-separated tokens either positionally or via --keys, normalizes them to lowercase, then hands the joined list to AutomationServiceBridge.hotkey. If you provide both, the positional value wins.

Key options

Flag Description
keys / --keys "cmd,c" Required list of keys (positional or --keys). Use commas or spaces; modifiers (cmd, alt, ctrl, shift, fn) can be mixed with letters/numbers/special keys.
--hold-duration <ms> Milliseconds to hold the combo before releasing (default 50).
Target flags --app <name>, --pid <pid>, --window-id <id>, --window-title <title>, --window-index <n> — focus a specific app/window before firing the hotkey. (--window-title/--window-index require --app or --pid; --window-id does not.)
--snapshot <id> Optional snapshot ID used for validation/focus (no implicit “latest snapshot” lookup).
Focus flags All FocusCommandOptions flags apply; focus runs when --snapshot or a target flag is present.

Implementation notes

  • The command errors if no keys are provided (either positionally or via --keys).
  • When both forms are present, the positional value is used.
  • Keys are parsed into an ordered list (press order) and rejoined with commas before calling the automation service, which expects cmd,shift,p style input and releases keys in reverse order.
  • If you omit both --snapshot and the target flags, the command skips focus entirely; this is handy for OS-global shortcuts like Spotlight, but for app-specific shortcuts you should provide a target or reuse the see snapshot.
  • JSON mode returns the normalized key list, total count, and elapsed time, which is useful when logging scripted shortcuts.

Examples

# Copy the current selection
peekaboo hotkey "cmd,c"

# Reopen the last closed tab in Safari
peekaboo hotkey --keys "cmd,shift,t" --snapshot $(jq -r '.data.snapshot_id' /tmp/see.json)

# Trigger Spotlight without needing a snapshot
peekaboo hotkey --keys "cmd space" --no-auto-focus

# Tab backwards using Shift+Tab (positional, space-separated)
peekaboo hotkey "shift tab"

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.