When to use
- Inspecting a running Windows app's UI from the command line
- AI agents interacting with Windows applications (clicking buttons, reading text, taking screenshots)
- Verifying UI state during development or testing
- Automating UI workflows without Playwright or Selenium
- Debugging WinUI 3, WPF, WinForms, Win32, or Electron app UIs
Prerequisites
- For UIA mode (any app): No setup needed — works with any running Windows app
- For input-injecting verbs (
click, hover, drag, touch, pen, scroll --wheel, send-keys --via send-input): an unlocked, interactive desktop with the target window foregroundable. On a locked/secure desktop they fail fast with no_interactive_desktop. The UIA-pattern verbs (inspect, search, get-*, wait-for, set-value, invoke, scroll --direction/--to, screenshot) are headless/locked-session friendly — prefer them in CI.
Common patterns
Discover and interact
Find visible text and click it
Navigate multi-page apps
Disambiguate duplicate elements
Key concepts
- Selector brackets:
inspect and search output shows selectors in [brackets] — use the bracketed value with other ui commands. Selectors are either AutomationId (stable, developer-set) or generated slug (e.g., btn-name-hash).
- AutomationId selectors: When an element has a unique AutomationId, it becomes the selector directly (e.g.,
[MinimizeButton]). These survive layout changes and localization — preferred for stable targeting.
- Slug selectors: When no unique AutomationId exists, a generated slug is used (e.g.,
[btn-close-a2b3]). Format: prefix-name-hash. May go stale after UI changes.
- Plain text search:
search and invoke accept plain text — search Minimize finds elements with "Minimize" in their Name or AutomationId (substring, case-insensitive). No special syntax needed.
--interactive flag: Filters to invokable elements only with auto-depth 8 — the fastest way to see what you can click- Invokable ancestor surfacing: When a search result isn't invokable, the nearest invokable parent is shown with its selector
; chaining: Chain commands with ; to run multiple operations in one call, reducing agent round-trips-a vs -w: Use -a to find apps by name/title/PID. Use -w <HWND> for stable window targeting- Element markers:
[on]/[off] for toggles, [collapsed]/[expanded], [scroll:v]/[scroll:h]/[scroll:vh] for scrollable containers, [offscreen], [disabled], value="..." for editable elements
Usage
Connect and discover
Inspect element tree
Find elements
Screenshot
Record video (H.264 MP4)
Record the window — or a single element's region — to an MP4. Frames are captured via Windows
Graphics Capture (PrintWindow/screen-DC fallback) and encoded incrementally with Media Foundation, so long
captures never buffer in memory. By default records until stopped; use --duration-sec N for a timed run.
- Default
--duration-sec 0 records until stopped — Ctrl+C for interactive use, or a newline / EOF on stdin for programmatic callers (pipe "" or close stdin to stop). A valid MP4 is always finalized on any graceful stop.
--capture-screen captures from the screen DC so overlays and popups are included; the window is brought to the foreground first. When WGC is unavailable and --capture-screen is not passed, the CLI returns an error — re-run with --capture-screen to consent to screen-DC capture.- Providing a selector that doesn't match any element fails immediately with
element_not_found (rather than silently recording the whole window).
--json stdout result: path, frames, width, height, fileSize, codec ("h264"), mode (wgc, printwindow, or screen). A {"event":"recording-started","path":"…","fps":N,"durationSec":N} liveness event is emitted to stderr as soon as capture begins, before the final result.
Hover (for tooltips, flyouts, hover states)
--dwell-time <ms> sets how long to wait after hovering (default: 800, range: 0–10000).
Send keyboard input
Synthesize keystrokes — the keyboard counterpart to click. Use for arrow/Tab/Enter navigation, shortcuts, and per-keystroke typing (vs set-value's atomic write). Tokens are whitespace-separated: named keys (enter, down, tab, esc, f5), modifier combos (ctrl+shift+t), literal text (hello), and raw virtual keys (vk=0xNN).
- Default
post-message is HWND-targeted and works across integrity levels, but can't fire WH_KEYBOARD_LL global hotkeys. It automatically retargets to the focused child control of the target window, so classic Win32/WinForms child-window controls (e.g. an edit box) receive the input. WinUI 3 / UWP / XAML controls are windowless and ignore posted WM_CHAR/WM_KEYDOWN — post-message can't deliver keys or text to them (the command emits a warning and still exits 0, since PostMessage can't confirm delivery). Use --via send-input for WinUI 3 / UWP / XAML apps.
- A token that collides with a key/modifier name (e.g.
enter, down, ctrl+a) is pressed as that key. Prefix it with text= to type it as literal text instead — text=enter types the word "enter"; chain text= tokens to type a literal phrase like text=down text=down text=enter. Backslash escapes inside a text= value type whitespace the tokenizer would otherwise collapse: \s→space, \t→tab, \n→newline, \r→CR, \\→backslash (e.g. text=a\s\sb → "a b"). When the whole argument is literal text, pass --verbatim instead of escaping each token: it types the entire keys argument as-is (no key/combo/vk=/text= parsing) and preserves exact whitespace — send-keys "down down enter" --verbatim types the words. (--verbatim does not decode backslash escapes; use a text= token for control characters.)
send-input is fully real input but goes to the foreground window and is UIPI-blocked when injecting from elevated → AppContainer/AppX. It rejects system-reserved combos (win+l, alt+f4, ctrl+shift+esc, ctrl+alt+del, alt+tab, …) because those act on the OS/shell, not just the target — pass --allow-system-keys to opt in (e.g. to fire a global hotkey such as PowerToys' win+shift+v or win+r), or use --via post-message (window-scoped) to send one straight to the window. win+l and ctrl+alt+del stay blocked even with --allow-system-keys — win+l locks the workstation via LockWorkStation() (unrecoverable from automation), and ctrl+alt+del is a Secure Attention Sequence (SAS) that Windows drops from injected input regardless of the flag, so it errors (invalid_arguments) instead of falsely reporting success. On a locked/secure desktop send-input fails fast with no_interactive_desktop.- Per-keystroke events: named keys/combos fire a real
KeyDown on both transports. For literal typed text, --via send-input maps each char to its VK (+Shift) so each character fires a real KeyDown + OS-composed WM_CHAR (TextChanged) — use it when downstream logic keys off KeyDown (e.g. WinUI 3/WPF TextBox); bring the target window to the foreground first. --via post-message posts a WM_CHAR per character to the focused child control (raises TextChanged, lands correct text into classic Win32 controls across integrity levels) but does not fire a per-character KeyDown, and — because WinUI 3 / UWP / XAML controls are windowless — does not reach them at all (named keys and text alike); use --via send-input there.
- Long literal text on
--via send-input is auto-throttled: the text is split into small character chunks injected one SendInput at a time with a brief pause between the chunks of that one run, so the target can drain its input queue and every character lands. A single unbroken burst overruns the queue and silently drops characters even though the command reports success. The pacing is scoped to a single long text run — short text, key names, and modifier combos (including sequences like ctrl+a delete) inject with no added delay, and the command emits an informational warning when a payload is large enough to be throttled. Because each paced chunk lands on whatever window is foreground, send-input re-verifies the target still owns the foreground before every continuation chunk and aborts with foreground_not_target if focus leaves the target mid-injection, so a focus change partway through can't spray the rest of the text into another window (a focus-changing chord such as alt+tab is exempt and is never treated as drift). For large bulk text, prefer set-value (atomic, no keystrokes or foreground needed) on controls that support it.
Drag (reorder, resize, sliders, drag-and-drop)
Press the mouse button at one point, move to another, then release with drag <from> <to>, where each endpoint is an element selector (uses its center) or screen x,y coordinates from ui inspect. Uses SendInput with intermediate moves so apps see a realistic WM_MOUSEMOVE stream.
- A selector drags from/to the element's center;
x,y are screen coordinates in the same space ui inspect/search report. Element endpoints are re-resolved just before the drag and fail with target_moved if still animating; on a locked/secure desktop the drag fails with no_interactive_desktop.
Touch gestures (tap, swipe, pinch, stretch, long-press)
Inject synthetic touch. The contact anchor is an element selector (its center) or an explicit --at x,y screen coordinate. Prefers the modern synthetic-pointer device and falls back to the legacy touch-injection API.
- Gestures:
tap (default), double-tap, long-press, swipe, pinch, stretch. --fingers 1–10 (pinch/stretch always 2). Refuses without a non-zero foregrounded target (no_target/foreground_not_target/no_interactive_desktop); every coordinate is checked against the target window, and a point outside it produces a non-fatal warning (warnings[] in --json) while injection still proceeds — consistent with the mouse verbs. If injected touch is unsupported on the device, the command surfaces the real Win32 error rather than a false success. In a Remote Desktop/VM session delivery isn't guaranteed even on exit 0 — the command appends a delivery-uncertainty warning (warnings[] in --json); verify the effect with a screenshot.
Pen / stylus (taps and ink strokes)
Inject synthetic pen input (Windows 10 1809+). Target an element center, an explicit --at, or a full --path ink stroke, with pressure/tilt/eraser control.
--pressure 0.0–1.0, --tilt-x/--tilt-y ±90°, --eraser for the eraser end. Same injection safety as touch: requires a non-zero foregrounded target window and checks every ink point (out-of-window → non-fatal warnings[] advisory, injection still proceeds). Pen routing is especially unreliable over Remote Desktop — exit 0 can mean the call succeeded but no pen reached the app; the command appends a delivery-uncertainty warning (warnings[] in --json). Validate pen flows on a local interactive desktop.
Read element state
Set values
set-value writes programmatically (no keystrokes, no foreground) via a fallback chain: ValuePattern → RangeValuePattern (numeric) → LegacyIAccessible put_accValue for TextPattern-only edit controls.
- The LegacyIAccessible fallback reaches rich-edit/compose controls that expose no ValuePattern, as long as their accessibility implements
put_accValue (native Win32 rich-edit and Chromium/Electron/WebView2 compose boxes typically do).
- WinUI 3
RichEditBox and WPF RichTextBox don't support programmatic value-setting — by design they're read-only to UI Automation's value APIs (Text pattern, no settable Value pattern). set-value fails on them with a clear error — use send-keys (needs an unlocked, foregrounded desktop) to type into those instead. Note get-value can still read them via TextPattern.
Scroll containers
Wait for UI state
Tips
- Use
--interactive with inspect as your first command — it shows only what you can click
- Chain commands with
; to reduce round-trips (see note below on why not &&)
- Use slugs from output to target specific elements — they're hash-validated and shell-safe
- Use plain text search to find elements:
search Minimize, invoke Submit
- When multiple elements match text search, the error shows slugs for each — pick the right one
- Use
get-property --property ToggleState to verify checkbox/toggle state after invoke
scroll auto-finds the nearest scrollable parent- Use
--capture-screen to capture popup overlays, dropdown menus, and flyouts (also brings the window to the foreground)
- Use
hover before screenshot --capture-screen to capture tooltips and hover-triggered UI
- Use
--focus to foreground the target window before capture without switching to screen-DC capture (default capture path uses Windows.Graphics.Capture and works while occluded)
- Use
--hide-disabled and --hide-offscreen to reduce noise
Why ; instead of &&
Use ; (not &&) to chain commands. PowerShell's && operator can freeze when a native CLI writes to stderr or uses ANSI escape sequences — this causes a pipeline deadlock. ; runs each command unconditionally and avoids this issue. This is also better for agent workflows: you usually want the screenshot to run even if the invoke had a non-zero exit (to see what went wrong).
File dialog workaround
File open/save dialogs are standard Windows dialogs with UIA support. Interact with them using existing commands:
Note: The filename input in standard file dialogs typically has AutomationId 1148. Use inspect -w <dialog-hwnd> --interactive to discover the actual slugs.
JSON output envelopes (v0.3.1+)
The --json envelope for ui inspect, ui get-focused, ui search, and ui wait-for was reshaped in v0.3.1. Pre-0.3.1 parsers will silently break — most fields were renamed, removed, or moved into envelopes. Highlights:
ui inspect --json now nests elements under windows[].elements[] (was a flat elements[]).ui get-focused --json always emits an envelope — { "hasFocus": false } or { "hasFocus": true, "element": {...} } (was bare null).ui search --json / ui wait-for --json may include an invokableAncestor field (element-shaped) on each match.- Per-element
id, parentSelector, and windowHandle are removed — use selector as the public handle.
Full schemas with examples: references/ui-json-envelope.md.
Related skills
winapp-setup for adding Windows SDK to your projectwinapp-package for packaging apps as MSIX
Troubleshooting
| Error | Cause | Solution |
|---|
| "No running app found" | Wrong name or app not running | Try process name, window title, or PID |
| "Multiple windows match" | Several windows match -a | Use -w <HWND> from the listed options |
| "Selector matched N elements" | Text query matches multiple elements | Use a slug from the suggestions shown in the error, or from inspect output |
| "Element may have changed" | Slug hash doesn't match current element | Re-run inspect to get fresh slugs |
| "does not support any invoke pattern" | Element can't be invoked | The error shows the invokable ancestor slug if one exists — use that |
| "No UIA window found" | UIA can't see the window | Use list-windows to find HWND, then -w |
| Popup not in screenshot | Default capture path doesn't include unowned overlays | Use --capture-screen flag |
element_not_found during record | Selector given but element not in tree | Re-run inspect or search to get a fresh selector |
ambiguous_selector during record | Plain-text selector matched multiple elements | Use a slug from the suggestions in the error message, or from inspect output |
| WGC unavailable during record | WGC capture init failed; no silent fallback | Check GPU/driver; use --capture-screen to explicitly request screen DC capture |
Command Reference
winapp ui status
Connect to a target app and display connection info.
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui inspect
View the UI element tree with semantic slugs, element types, names, and bounds.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--ancestors | Walk up the tree from the specified element to the root | (none) |
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--depth | Tree inspection depth | 4 |
--hide-disabled | Hide disabled elements from output | (none) |
--hide-offscreen | Hide offscreen elements from output | (none) |
--interactive | Show only interactive/invokable elements (buttons, links, inputs, list items). Increases default depth to 8. | (none) |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui search
Search the element tree for elements matching a text query. Returns all matches with semantic slugs.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--max | Maximum search results | 50 |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui get-property
Read UIA property values from an element. Specify --property for a single property or omit for all.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--property | Property name to read or filter on | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui get-value
Read the current value from an element. Tries TextPattern (RichEditBox, Document), ValuePattern (TextBox, ComboBox, Slider), then Name (labels). Usage: winapp ui get-value -a
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui screenshot
Capture the target window or element as a PNG image. When multiple windows exist (e.g., dialogs), captures each to a separate file. With --json, returns file path and dimensions. Use --capture-screen for popup overlays.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--capture-screen | Capture from screen DC via BitBlt (includes popups/overlays not owned by the target). | (none) |
--focus | Bring the target window to the foreground before capture. Already implied by --capture-screen. | (none) |
--json | Format output as JSON | (none) |
--output | Save output to this file path. | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui record
Record the target window (or an element's region) to an H.264 MP4 video. Captures frames via Windows Graphics Capture and encodes with Media Foundation. By default records until stopped (Ctrl+C, or a newline/EOF on stdin for programmatic callers). Use --duration-sec N for a timed run. A valid MP4 is always finalized on graceful stop. Use --capture-screen to include overlays/popups.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--capture-screen | Capture from screen DC via BitBlt (includes popups/overlays not owned by the target). | (none) |
--duration-sec | Recording duration in seconds. Default 0 records until stopped — Ctrl+C, or (for programmatic callers) a newline or EOF on stdin. A valid MP4 is always finalized on graceful stop. | (none) |
--fps | Frames per second to capture | 15 |
--json | Format output as JSON | (none) |
--max-edge | Downscale so the longest edge is at most this many pixels (0 = no downscale) | (none) |
--output | Save output to this file path. | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui invoke
Activate an element by slug or text search. Tries InvokePattern, TogglePattern, SelectionItemPattern, and ExpandCollapsePattern in order.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui click
Click an element by slug or text search using mouse simulation. Works on elements that don't support InvokePattern (e.g., column headers, list items). Use --double for double-click, --right for right-click.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--double | Perform a double-click instead of a single click | (none) |
--json | Format output as JSON | (none) |
--right | Perform a right-click instead of a left click | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui drag
Press the mouse button at one point, move to another, then release. 'drag ', where / are each an element selector (uses the element's center) or screen x,y coordinates as reported by 'ui inspect'. Useful for reorder/resize/slider gestures and drag-and-drop. Use --right for a right-button drag, --hold-ms for press-and-hold/long-press, and --dwell-ms to settle on a drop target before releasing.
Arguments
| Argument | Required | Description |
|---|
<from> | No | Start point — an element selector (drags from its center) or screen coordinates x,y as reported by 'ui inspect' (e.g. pn-list-d736 or 100,200). |
<to> | No | End point — an element selector (drops at its center) or screen coordinates x,y as reported by 'ui inspect' (e.g. pn-target-d746 or 300,400). |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--dwell-ms | Milliseconds to dwell at the destination after moving, before releasing (default: 0). Lets drop targets / merge overlays that arm from a sustained hover latch before release. | (none) |
--hold-ms | Milliseconds to hold the button down at the start before moving (default: 0). With == (no movement) this performs a press-and-hold / long-press gesture. | (none) |
--json | Format output as JSON | (none) |
--right | Drag with the right mouse button instead of the left button | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui touch
Inject synthetic touch input using the Windows touch-injection API. Supports tap, double-tap, long-press, swipe, pinch and stretch gestures at an element's center or explicit screen x,y coordinates. Requires an unlocked, interactive desktop with the target window foregroundable.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--at | Explicit start point as screen coordinates x,y (as reported by 'ui inspect'). Defaults to the selector's element center. | (none) |
--direction | Swipe direction: right (default), left, up, or down. Combined with --distance to compute the end point when --to-point is not given. | right |
--distance | Distance in pixels for pinch/stretch (finger spread) or swipe. | (none) |
--duration-ms | Glide time in milliseconds for moving gestures (swipe/pinch/stretch). | 300 |
--fingers | Number of touch contacts (default: 1). Pinch/stretch always use 2. | 1 |
--gesture | Gesture to perform: tap, double-tap, long-press, swipe, pinch, stretch (default: tap). | tap |
--hold-ms | Milliseconds to hold contacts down before lifting (long-press hold time). Defaults to 500 ms when --gesture long-press is used and this option is not set. | (none) |
--json | Format output as JSON | (none) |
--to-point | End point x,y for a swipe (screen coordinates). Takes precedence over --direction. | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui pen
Inject synthetic pen/stylus input using the Windows synthetic-pointer API. Taps or draws ink strokes with configurable pressure, tilt and eraser mode, at an element's center or explicit screen x,y coordinates. Requires an unlocked, interactive desktop with the target window foregroundable (Windows 10 1809+).
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--at | Pen contact point as screen coordinates x,y (as reported by 'ui inspect'). Defaults to the selector's element center. Ignored when --path is given. | (none) |
--duration-ms | Total glide time in milliseconds distributed across the stroke path segments (default: ~10 ms per segment). | (none) |
--eraser | Use the eraser end of the pen instead of the tip. | (none) |
--json | Format output as JSON | (none) |
--path | Ink stroke path as a whitespace-separated list of x,y pairs, e.g. "10,10 20,30 40,50". | (none) |
--pressure | Pen pressure from 0.0 to 1.0 (default: 0.5). | 0.5 |
--tilt-x | Pen tilt along the x-axis in degrees (-90 to 90, default: 0). | (none) |
--tilt-y | Pen tilt along the y-axis in degrees (-90 to 90, default: 0). | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui hover
Move the mouse to an element's center to trigger hover effects (tooltips, flyouts, visual states). Uses SendInput for realistic mouse movement and waits for a configurable dwell time.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--dwell-time | Time in milliseconds to wait after hovering for hover effects to appear (default: 800) | 800 |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui send-keys
Send synthetic keyboard input to a window. Supports named keys (down, enter, tab), modifier combos (ctrl+shift+t), raw virtual keys (vk=0xNN), and literal text. Use --verbatim to type the whole argument literally, or --target to focus an element first. Two transports via --via: post-message (default, HWND-targeted, bypasses UIPI) or send-input (OS-wide). For per-keystroke KeyDown on typed text (e.g. a WinUI 3/WPF TextBox), use --via send-input.
Arguments
| Argument | Required | Description |
|---|
<keys> | No | Keys to send. Whitespace-separated tokens: named keys (down, enter, tab, esc, f5), modifier combos (ctrl+shift+t, alt+f4), raw virtual keys (vk=0x42), or literal text (hello). Use text= to type a single value verbatim when it would otherwise be read as a key name or combo (text=enter types "enter"; text=ctrl+a types "ctrl+a"); backslash escapes \s \t \n \r \ are supported (text=a\s\sb types "a b"). To type the whole argument literally without escaping each token, pass --verbatim instead. Quote multi-token strings, e.g. "ctrl+a delete". |
Options
| Option | Description | Default |
|---|
--allow-system-keys | Allow synthesizing system-/shell-reserved combos (win+, alt+f4, alt+tab, ctrl+esc, …) via --via send-input, which are refused by default because they act on the OS/shell beyond the target app. Opt in to drive global hotkeys (e.g. PowerToys' win+shift+v, win+r). No effect on --via post-message (already window-scoped; a warning is emitted if set without send-input). Note: win+l and ctrl+alt+del stay blocked even with this flag — win+l locks the workstation (LockWorkStation() via the shell hook), which is unrecoverable from automation, and ctrl+alt+del is a Secure Attention Sequence (SAS) that Windows drops from injected input regardless of this flag, so it can never take effect. | (none) |
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--target | Optional selector (slug or text) to focus before sending keys. | (none) |
--verbatim | Type the entire keys argument as literal text — no named-key, combo, or vk= interpretation, and exact whitespace preserved. The whole-argument form of the per-token text= escape: --verbatim "down down enter" types the words instead of pressing Down, Down, Enter. | (none) |
--via | Transport: post-message (default, HWND-targeted, bypasses UIPI; typed text raises TextChanged but not a per-character KeyDown) or send-input (OS-wide; typed text raises a real per-character KeyDown + TextChanged). Named keys and combos raise KeyDown on both, but keyboard accelerators/shortcuts (KeyboardAccelerator, e.g. ctrl+t) only fire via send-input. post-message targets the focused child control and works for classic Win32/WinForms controls, but WinUI 3 / UWP / XAML controls are windowless and ignore posted messages — use send-input for those (a warning is emitted when the target looks like a XAML app). | post-message |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui set-value
Set a value on an element programmatically. Works for TextBox, ComboBox, Slider, and other editable controls via UIA ValuePattern/RangeValuePattern, with a LegacyIAccessible (put_accValue) fallback for TextPattern-only edit controls — no app foreground required. Some rich text controls (e.g. WinUI 3 RichEditBox and WPF RichTextBox) don't support setting their value programmatically — use the 'send-keys' command with '--via send-input' to type into them instead. Usage: winapp ui set-value -a
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
<value> | No | Value to set (text for TextBox/ComboBox, number for Slider) |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui focus
Move keyboard focus to the specified element using UIA SetFocus.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui scroll-into-view
Scroll the specified element into the visible area using UIA ScrollItemPattern.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui scroll
Scroll a container element using ScrollPattern. Use --direction to scroll incrementally, --to to jump to top/bottom, or --wheel to synthesize mouse-wheel input.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--direction | Scroll direction: up, down, left, right | (none) |
--json | Format output as JSON | (none) |
--to | Scroll to position: top, bottom | (none) |
--wheel | Rotate the mouse wheel over the element by this many notches (1 = one notch up, -1 = one notch down). Synthesizes real wheel input instead of using ScrollPattern. | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui wait-for
Wait for an element to appear, disappear, or have a property reach a target value. Polls at 100ms intervals until condition met or timeout.
Arguments
| Argument | Required | Description |
|---|
<selector> | No | Semantic slug (e.g., btn-minimize-d1a0) or text to search by name/automationId |
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--contains | Use substring matching for --value instead of exact match | (none) |
--gone | Wait for element to disappear instead of appear | (none) |
--json | Format output as JSON | (none) |
--property | Property name to read or filter on | (none) |
--timeout | Timeout in milliseconds | 5000 |
--value | Wait for element value to equal this string. Uses smart fallback (TextPattern -> ValuePattern -> Name). Combine with --property to check a specific property instead. | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |
winapp ui list-windows
List all visible windows with their HWND, title, process, and size. Use -a to filter by app name. Use the HWND with -w to target a specific window.
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--show-hidden | Include untitled zero-size windows that are hidden by default | (none) |
winapp ui get-focused
Show the element that currently has keyboard focus in the target app.
Options
| Option | Description | Default |
|---|
--app | Target app (process name, window title, or PID). Lists windows if ambiguous. | (none) |
--json | Format output as JSON | (none) |
--window | Target window by HWND (stable handle from list output). Takes precedence over --app. | (none) |