peekaboo hotkey

hotkey sends one shortcut chord (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 Peekaboo can resolve a target process from app, PID, window, or snapshot metadata, delivery is background by default; pass --foreground for focused/global hotkeys. If you provide both key forms, the positional value wins.

#Key options

#Delivery modes

• Background is the default when Peekaboo can resolve a target process from target flags or snapshot metadata. It posts the shortcut to that process without activating the app.
• Foreground (--foreground) focuses the target first and sends the shortcut as focused/global input. Use it when the app only handles shortcuts for its key window.
• If you omit target flags and --snapshot, hotkey sends a foreground/global shortcut to the current focus, which is useful for OS-level shortcuts.

#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.
• Background hotkeys are parsed as one non-modifier key plus optional modifiers, such as cmd,l or cmd,shift,p. For key sequences, use press or another command that models sequential input.
• Background delivery uses CoreGraphics process-targeted keyboard events. Peekaboo preflights event-posting permission and confirms the target process is running before sending the event, but postToPid does not confirm delivery or that the app handled the shortcut. Apps that only handle shortcuts for their focused key window may ignore these events while in the background.
• If you omit both --snapshot and the target flags, the command sends a foreground/global hotkey to the current focus; 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, delivery mode, optional target PID, 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

# Focus Safari's address field without bringing Safari forward
peekaboo hotkey "cmd,l" --app Safari

# Force foreground delivery for apps that require the focused key window
peekaboo hotkey "cmd,l" --app Safari --foreground

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

#Troubleshooting

• Verify Screen Recording + Accessibility permissions (peekaboo permissions status). Background hotkeys also require Event Synthesizing access for the process that sends the event; request it with peekaboo permissions request-event-synthesizing. When Peekaboo is using a remote bridge host, that command requests access for the bridge host. Use --no-remote only when you want to grant the local CLI process.
• 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.