Key and shortcut tools

Press and release one key. delivery_mode as in click/type_text.

• background (default): posts to the pid without raising the window; with element_token it focuses that element first.
• foreground: fronts the exact window (needs window_id), sends a real HID key transition (Chromium content, inline editors, menu equivalents), then restores the prior app.

Confirmed only when a native AX value/selection read-back changes; otherwise effect:"unverifiable" (not a delivery failure). Keys: return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, any letter or digit.

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. Background key events never reach a native app's menus, so when the combo is a menu item's key equivalent (cmd+s, cmd+w, ...) and the app is not in front, that menu item runs through accessibility instead (a disabled Save is saved through the app's scripting interface and verified on disk); a menu item macOS keeps disabled in the background is refused with background_unavailable, and no keys are sent. • 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