Key and shortcut tools

Press and release a single key. Follows the same delivery_mode ladder as click/type_text: it does NOT raise the window by default: • background (default): post to the pid WITHOUT fronting/raising; the auth-message path (Chromium-safe). With element_token it focuses that AX element first. window_id only targets; it does not raise. • foreground: guard and briefly front the exact window, focus an addressed AX element when supplied, send a genuine HID key transition so Chromium content, inline editors, and native menu equivalents receive it, then restore prior frontmost. Requires window_id.

A key press is confirmed only when a bounded native AX value/selection read-back changes on the same control. Otherwise a successfully attempted post remains effect:"unverifiable" without implying delivery failure or recommending foreground. Key names: return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, plus any letter or digit. Modifiers array: cmd, shift, option/alt, ctrl, fn.

macOS parameters

Press a key combination: e.g. ["cmd", "c"] for Copy, ["cmd", "shift", "4"] for screenshot selection. Follows the same delivery_mode ladder as click/type_text: it does NOT raise the window by default: • background (default): post the combo to the target pid WITHOUT fronting or raising it; uses the macOS 14+ auth-message envelope so Chromium/Electron accept it as trusted live input. With an AX target, focus that exact element first. No top-level focus steal. window_id here only targets the combo; it does not raise. • foreground: briefly front the window (NSMenu path, < 1 ms via SLPSSetFrontProcessWithOptions) so native menu key-equivalents (Cmd+Z, Cmd+W) dispatch, then restore the prior frontmost; the explicit escalation for menu-bar shortcuts on non-Chromium apps that ignore a background combo. With an AX target or x,y, the focused field receives the chord through the foreground HID queue (needed by native Chromium fields such as the omnibox). Requires window_id.

A combo is never driver-verifiable (no read-back) → effect:"unverifiable"; confirm via screenshot. NOTE: a keyboard combo does NOT focus a text field; to type into a backgrounded Electron input, establish real renderer focus with a PIXEL click first, then type_text. If an app only accepts paste, call clipboard_write, then clipboard_read and verify its types (and text when applicable) before selecting or replacing editor content; only then send Cmd+V.

Recognized modifiers: cmd/command, shift, option/alt, ctrl/control, fn. Non-modifier keys use the same vocabulary as press_key. Order: modifiers first, one non-modifier last.

macOS parameters