# olef ui

Source: https://olef.dev/docs/reference/cli/ui

Generated from **Olef 3.0.2**. [All commands](https://olef.dev/docs/reference/commands) · [Capabilities and requirements](https://olef.dev/docs/reference/capabilities)

These entries describe available commands, not a sequence to run. Check prerequisites before changing app, device, or cloud state. Global options are listed in the [command catalog](https://olef.dev/docs/reference/commands#global-options).

## olef ui

Live UI automation: dump, find, tap, type, and wait for screen state

```bash
olef ui --help
```

Output: **json**.

### olef ui dump

Dump the current UI as a flat element list

```bash
olef ui dump --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--full` | Emit the full element set (bounds + every UIAutomator flag). Default is the compact agent shape: selector fields + tap, false flags omitted |
| `--deep` | Ask the runtime's Compose inspector for semantics/layout nodes that are missing from the accessibility tree (attaches the runtime) |
| `--deep-timeout-ms <DEEP_TIMEOUT_MS>` | Budget for --deep's Compose semantics read, in milliseconds Default: `8000`. |
| `--since <SCREEN_HASH>` | A `screen_hash` from an earlier read: report only what changed since that screen (`unchanged: true` when nothing did). Falls back to the full element list when that screen is no longer remembered |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui audit

Audit the current screen for interactive elements lacking a stable selector (resource-id / Compose testTag) — the ones that force a test to match on localized text or element index. Helps before writing a test. With --a11y, audit accessibility instead

```bash
olef ui audit --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--a11y` | Check accessibility instead of selectors: unlabeled controls, touch targets under 48dp, low text contrast, duplicate names, stacked clickables and role words in descriptions. Takes one screenshot |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui gen

Generate a starting-point Kotlin Screen Object from the current screen, with stable selectors filled in and un-tagged elements listed as TODOs

```bash
olef ui gen --help
```

Output: **source_text**.

| Argument | Description |
| --- | --- |
| `--name <NAME>` | Class-name prefix; the generated class is `<name>Screen` Default: `Generated`. |

### olef ui screenshot

Capture a screenshot to a file

```bash
olef ui screenshot --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<path>` |  |
| `--format <FORMAT>` | Image format: png (default) or jpeg |
| `--scale <SCALE>` | Server-side downscale factor, e.g. 0.5 |
| `--quality <QUALITY>` | JPEG quality 1..100 (format=jpeg only) |
| `--redact-pixels` | With global --redact enabled, black out accessibility bounds whose text matches the active policy. PNG only; pixels remain potentially sensitive because Android may not expose every rendered glyph |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui find

Find elements by selector (--text/--rid/--desc/--xpath); does not tap

```bash
olef ui find --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--text <TEXT>` | Match by visible text (normalized, case-insensitive substring; add --exact for a full match) |
| `--rid <RID>` | Match by resource-id (substring) |
| `--desc <DESC>` | Match by content-description (normalized substring) |
| `--xpath <XPATH>` | Match by xpath, e.g. //*[@text='Foo'] or //*[contains(@text,'Foo')] |
| `--all` | Return all matches instead of the first |
| `--exact` | Match selector values exactly instead of as a substring |
| `--clickable` | Only match clickable elements (skips labels/containers with the same text) |
| `--full` | Emit the full element set instead of the compact agent shape |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui tap

Tap by element id, coordinates, or a selector (--text/--rid/--desc/--xpath)

```bash
olef ui tap --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--handle <HANDLE>` | Screen-bound handle from a fresh `ui dump` (i:.../e:...) |
| `--id <ID>` | Element id from a fresh `ui dump`. Equivalent to positional `ui tap <id>` |
| `--fallback-id <FALLBACK_ID>` | Compose fallback id (cs:&lt;draw-id&gt; or cl:&lt;draw-id&gt;) from a fresh `ui dump --deep`. High-confidence cs: targets may be tapped directly; cl: targets require --coordinate-fallback and --if-screen |
| `<a>` | Element id (from `ui dump`) or X coordinate |
| `<b>` | Y coordinate (with X for a coordinate tap) |
| `--text <TEXT>` | Tap the element matching this visible text (normalized substring; --exact for full) |
| `--rid <RID>` | Tap the element matching this resource-id (substring) |
| `--desc <DESC>` | Tap the element matching this content-description (substring) |
| `--xpath <XPATH>` | Tap the element matching this xpath |
| `--exact` | Match selector values exactly instead of as a substring. Avoids tapping a label whose text merely contains the target (e.g. "Allow notifications…" vs "Allow") |
| `--clickable` | Require the matched node itself to be clickable instead of resolving its nearest enabled clickable ancestor |
| `--coordinate-fallback` | Explicitly allow center-coordinate injection when no enabled clickable target can perform ACTION_CLICK. Selector taps otherwise fail safely |
| `--allow-occluded` | Tap even when the target is covered by the keyboard, a dialog, a system bar or an element drawn on top. Id and selector taps are otherwise refused with `element_occluded`, because a user's finger would land on the cover instead |
| `--deep-timeout-ms <DEEP_TIMEOUT_MS>` | Budget for --fallback-id's Compose semantics read, in milliseconds Default: `8000`. |
| `--via <HOW>` | How the tap reaches an element: `accessibility` (default: a click on its clickable node) or `touch` (a real finger tap at its visible point, for views that react to touches but not to clicks) Values: `accessibility`, `touch`. |
| `--wait-ms <MS>` | Wait up to this long for the target to be on screen, unique, enabled and uncovered before acting, re-reading the screen until it is. Nothing is injected while waiting. Default: one attempt |
| `--reveal` | Bring the target into view first: wait for the screen to settle, hide the keyboard when it hides or covers the target, then scroll the nearest list (down, then up) until the target shows. Needs --text, --rid or --desc |
| `--expect-checked <BOOL>` | Require the target to be checked afterwards (`false`: unchecked), read back on a stable screen. Switches, checkboxes, and Compose chips and toggles. Needs --text, --rid or --desc Values: `true`, `false`. |
| `--expect-selected <BOOL>` | Require the target to be selected afterwards (`false`: not selected). Tabs and list items; Compose reports selectable chips as checked Values: `true`, `false`. |
| `--expect-enabled <BOOL>` | Require the target to be enabled afterwards (`false`: disabled) Values: `true`, `false`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui set-progress

Set a slider/range control through Android accessibility and verify readback

```bash
olef ui set-progress --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--handle <HANDLE>` | Screen-bound handle from a fresh `ui dump` (i:.../e:...) |
| `--id <ID>` | Element id from a fresh `ui dump` |
| `--text <TEXT>` | Match by exact/normalized visible text |
| `--rid <RID>` | Match by resource id or Compose test tag |
| `--desc <DESC>` | Match by content description |
| `--xpath <XPATH>` | Match by supported xpath |
| `--exact` | Match selector values exactly instead of as a substring |
| `--value <VALUE>` | Absolute value in the control's exposed min..max range |
| `--percent <PERCENT>` | Position from 0 to 100 within the exposed range |
| `--clamp` | Clamp an out-of-range value/percent instead of rejecting it |
| `--coordinate-fallback` | Explicitly permit an approximate coordinate track click when semantic mutation is unavailable |
| `--wait-ms <MS>` | Wait up to this long for the target to be on screen, unique, enabled and uncovered before acting, re-reading the screen until it is. Nothing is injected while waiting. Default: one attempt |
| `--reveal` | Bring the target into view first: wait for the screen to settle, hide the keyboard when it hides or covers the target, then scroll the nearest list (down, then up) until the target shows. Needs --text, --rid or --desc |
| `--expect-checked <BOOL>` | Require the target to be checked afterwards (`false`: unchecked), read back on a stable screen. Switches, checkboxes, and Compose chips and toggles. Needs --text, --rid or --desc Values: `true`, `false`. |
| `--expect-selected <BOOL>` | Require the target to be selected afterwards (`false`: not selected). Tabs and list items; Compose reports selectable chips as checked Values: `true`, `false`. |
| `--expect-enabled <BOOL>` | Require the target to be enabled afterwards (`false`: disabled) Values: `true`, `false`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui double-tap

Double-tap an element (--rid/--text/--desc/--xpath/--id/--handle) or &lt;x&gt; &lt;y&gt; coordinates. An element is checked first: unique, enabled and not covered

```bash
olef ui double-tap --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<x>` | X coordinate, for a coordinate double-tap |
| `<y>` | Y coordinate, for a coordinate double-tap |
| `--handle <HANDLE>` | Screen-bound handle from a fresh `ui dump` (i:.../e:...) |
| `--id <ID>` | Element id from a fresh `ui dump` |
| `--text <TEXT>` | Match the element by visible text (normalized substring; --exact for full) |
| `--rid <RID>` | Match the element by resource-id or Compose test tag (substring) |
| `--desc <DESC>` | Match the element by content-description (substring) |
| `--xpath <XPATH>` | Match the element by xpath |
| `--exact` | Match selector values exactly instead of as a substring |
| `--allow-occluded` | Act even when the element is covered by the keyboard, a dialog, a system bar or an element drawn on top (refused with `element_occluded` otherwise) |
| `--wait-ms <MS>` | Wait up to this long for the target to be on screen, unique, enabled and uncovered before acting, re-reading the screen until it is. Nothing is injected while waiting. Default: one attempt |
| `--reveal` | Bring the target into view first: wait for the screen to settle, hide the keyboard when it hides or covers the target, then scroll the nearest list (down, then up) until the target shows. Needs --text, --rid or --desc |
| `--expect-checked <BOOL>` | Require the target to be checked afterwards (`false`: unchecked), read back on a stable screen. Switches, checkboxes, and Compose chips and toggles. Needs --text, --rid or --desc Values: `true`, `false`. |
| `--expect-selected <BOOL>` | Require the target to be selected afterwards (`false`: not selected). Tabs and list items; Compose reports selectable chips as checked Values: `true`, `false`. |
| `--expect-enabled <BOOL>` | Require the target to be enabled afterwards (`false`: disabled) Values: `true`, `false`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui long-tap

Long-press an element (--rid/--text/--desc/--xpath/--id/--handle) or &lt;x&gt; &lt;y&gt; coordinates, holding for --duration-ms. An element is checked first: unique, enabled and not covered

```bash
olef ui long-tap --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<x>` | X coordinate, for a coordinate long-press |
| `<y>` | Y coordinate, for a coordinate long-press |
| `--handle <HANDLE>` | Screen-bound handle from a fresh `ui dump` (i:.../e:...) |
| `--id <ID>` | Element id from a fresh `ui dump` |
| `--text <TEXT>` | Match the element by visible text (normalized substring; --exact for full) |
| `--rid <RID>` | Match the element by resource-id or Compose test tag (substring) |
| `--desc <DESC>` | Match the element by content-description (substring) |
| `--xpath <XPATH>` | Match the element by xpath |
| `--exact` | Match selector values exactly instead of as a substring |
| `--allow-occluded` | Act even when the element is covered by the keyboard, a dialog, a system bar or an element drawn on top (refused with `element_occluded` otherwise) |
| `--duration-ms <DURATION_MS>` | How long to hold the press, in milliseconds Default: `600`. |
| `--wait-ms <MS>` | Wait up to this long for the target to be on screen, unique, enabled and uncovered before acting, re-reading the screen until it is. Nothing is injected while waiting. Default: one attempt |
| `--reveal` | Bring the target into view first: wait for the screen to settle, hide the keyboard when it hides or covers the target, then scroll the nearest list (down, then up) until the target shows. Needs --text, --rid or --desc |
| `--expect-checked <BOOL>` | Require the target to be checked afterwards (`false`: unchecked), read back on a stable screen. Switches, checkboxes, and Compose chips and toggles. Needs --text, --rid or --desc Values: `true`, `false`. |
| `--expect-selected <BOOL>` | Require the target to be selected afterwards (`false`: not selected). Tabs and list items; Compose reports selectable chips as checked Values: `true`, `false`. |
| `--expect-enabled <BOOL>` | Require the target to be enabled afterwards (`false`: disabled) Values: `true`, `false`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui swipe

Swipe from (x1,y1) to (x2,y2), or across an element (--rid/--text/--desc/--xpath/--id/--handle) in --direction: a carousel, a pager, a swipe-to-dismiss row

```bash
olef ui swipe --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<x1>` | Start X, for a coordinate swipe |
| `<y1>` | Start Y, for a coordinate swipe |
| `<x2>` | End X, for a coordinate swipe |
| `<y2>` | End Y, for a coordinate swipe |
| `--handle <HANDLE>` | Screen-bound handle from a fresh `ui dump` (i:.../e:...) |
| `--id <ID>` | Element id from a fresh `ui dump` |
| `--text <TEXT>` | Match the element by visible text (normalized substring; --exact for full) |
| `--rid <RID>` | Match the element by resource-id or Compose test tag (substring) |
| `--desc <DESC>` | Match the element by content-description (substring) |
| `--xpath <XPATH>` | Match the element by xpath |
| `--exact` | Match selector values exactly instead of as a substring |
| `--allow-occluded` | Act even when the element is covered by the keyboard, a dialog, a system bar or an element drawn on top (refused with `element_occluded` otherwise) |
| `--direction <DIRECTION>` | Finger direction of an element swipe: the finger moves up, down, left or right through the middle of the element Values: `up`, `down`, `left`, `right`. |
| `--scale <FRACTION>` | Fraction of the element's height or width an element swipe travels, 0.1–0.95 (default 0.6) |
| `--duration-ms <DURATION_MS>` | Swipe duration in milliseconds (longer = slower, more deliberate) Default: `200`. |
| `--wait-ms <MS>` | Wait up to this long for the target to be on screen, unique, enabled and uncovered before acting, re-reading the screen until it is. Nothing is injected while waiting. Default: one attempt |
| `--reveal` | Bring the target into view first: wait for the screen to settle, hide the keyboard when it hides or covers the target, then scroll the nearest list (down, then up) until the target shows. Needs --text, --rid or --desc |
| `--expect-checked <BOOL>` | Require the target to be checked afterwards (`false`: unchecked), read back on a stable screen. Switches, checkboxes, and Compose chips and toggles. Needs --text, --rid or --desc Values: `true`, `false`. |
| `--expect-selected <BOOL>` | Require the target to be selected afterwards (`false`: not selected). Tabs and list items; Compose reports selectable chips as checked Values: `true`, `false`. |
| `--expect-enabled <BOOL>` | Require the target to be enabled afterwards (`false`: disabled) Values: `true`, `false`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui drag

Drag from (x1,y1) to (x2,y2) — slower than swipe, for drag-and-drop / reorder

```bash
olef ui drag --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<x1>` | **Required.** |
| `<y1>` | **Required.** |
| `<x2>` | **Required.** |
| `<y2>` | **Required.** |
| `--duration-ms <DURATION_MS>` | Drag duration in milliseconds (longer = slower, for drag-and-drop) Default: `500`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui swipe-ext

Swipe a fraction (--scale) of the screen in a direction (up/down/left/right)

```bash
olef ui swipe-ext --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<direction>` | **Required.** Direction to swipe Values: `up`, `down`, `left`, `right`. |
| `--scale <SCALE>` | Fraction of the screen to travel, 0.0–1.0 Default: `0.9`. |
| `--duration-ms <DURATION_MS>` | Swipe duration in milliseconds Default: `200`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui path

Move one finger (or two, with `--fingers 2`) along timed points, for gestures `swipe`/`drag` can't make: curves, long-press-then-drag, pinch, rotate. Points are pixels: `x,y[,delay_ms]`, or `x1,y1,x2,y2[,delay_ms]` with two fingers; the delay comes before the point (default 16). The first point is touch-down, the last touch-up. Two fingers need an emulator

```bash
olef ui path --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<points>` | **Required.** The points, e.g. `500,1500 500,1200 500,800,100` |
| `--fingers <FINGERS>` | 1 or 2 Default: `1`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui pinch

Pinch in (zoom out) or out (zoom in) on the element matched by a selector

```bash
olef ui pinch --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<direction>` | **Required.** Pinch `in` (zoom out) or `out` (zoom in) Values: `in`, `out`. |
| `--rid <RID>` | Match the target element by resource-id (substring) |
| `--text <TEXT>` | Match the target element by visible text (substring) |
| `--desc <DESC>` | Match the target element by content-description (substring) |
| `--percent <PERCENT>` | Pinch distance as a percent of the element's size (1–100) Default: `50`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui scroll-to

Scroll a list until a selector is visible, then optionally tap it

```bash
olef ui scroll-to --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--text <TEXT>` | Match text by case-insensitive substring. Single-target actions prefer a unique full-text match; multiple remaining matches are ambiguous |
| `--rid <RID>` | Match by resource-id substring; actions prefer a unique exact match |
| `--desc <DESC>` | Match by content-description substring; actions prefer a unique exact match |
| `--direction <DIRECTION>` | Content scroll direction: down (default) reveals items further down Default: `down`. Values: `up`, `down`, `left`, `right`. |
| `--max-swipes <MAX_SWIPES>` | Maximum number of swipes before giving up Default: `12`. |
| `--container-rid <CONTAINER_RID>` | Restrict swiping to the bounds of the scrollable with this resource-id |
| `--tap` | Tap the element once found |
| `--exact` | Require the selector field to match the complete value |
| `--allow-occluded` | With --tap, tap even when the found element is covered (by the keyboard, a dialog, a bottom bar drawn on top); refused otherwise |
| `--duration-ms <DURATION_MS>` | Swipe duration in milliseconds Default: `250`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui focus

Move D-pad focus to a selector (TV/leanback), then optionally activate it (--center)

```bash
olef ui focus --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--text <TEXT>` | Match text by case-insensitive substring. Single-target actions prefer a unique full-text match; multiple remaining matches are ambiguous |
| `--rid <RID>` | Match by resource-id substring; actions prefer a unique exact match |
| `--desc <DESC>` | Match by content-description substring; actions prefer a unique exact match |
| `--center` | Press DPAD_CENTER once the target is focused (activate it) |
| `--exact` | Match the selector value exactly instead of as a case-insensitive substring. Use it to disambiguate when several elements match |
| `--max-steps <MAX_STEPS>` | Maximum D-pad presses before giving up Default: `30`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui text

Type into the focused field, or into an element matched by --id/--text/--rid/--desc/--xpath

```bash
olef ui text --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<value>` | The text to type. Use --value-env instead for secrets |
| `--value-env <NAME>` | Type the value of this environment variable, never echoing it: output names the variable, and the value is scrubbed from anything printed. For passwords and tokens (`--value-env LOGIN_PASSWORD`) Conflicts with: `value`. |
| `--clear` | Clear the field's existing contents before typing |
| `--handle <HANDLE>` | Screen-bound handle from a fresh `ui dump` (i:.../e:...) |
| `--id <ID>` | Element id from a fresh `ui dump` to receive text |
| `--text <TEXT>` | Match a text-bearing/editable element to receive text |
| `--rid <RID>` | Match by resource-id substring |
| `--desc <DESC>` | Match by content-description substring |
| `--xpath <XPATH>` | Match by xpath |
| `--exact` | Use exact selector matching instead of substring matching |
| `--wait-ms <MS>` | Wait up to this long for the target to be on screen, unique, enabled and uncovered before acting, re-reading the screen until it is. Nothing is injected while waiting. Default: one attempt |
| `--reveal` | Bring the target into view first: wait for the screen to settle, hide the keyboard when it hides or covers the target, then scroll the nearest list (down, then up) until the target shows. Needs --text, --rid or --desc |
| `--expect-checked <BOOL>` | Require the target to be checked afterwards (`false`: unchecked), read back on a stable screen. Switches, checkboxes, and Compose chips and toggles. Needs --text, --rid or --desc Values: `true`, `false`. |
| `--expect-selected <BOOL>` | Require the target to be selected afterwards (`false`: not selected). Tabs and list items; Compose reports selectable chips as checked Values: `true`, `false`. |
| `--expect-enabled <BOOL>` | Require the target to be enabled afterwards (`false`: disabled) Values: `true`, `false`. |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui pin

Enter a numeric PIN through visible keypad buttons without echoing it in JSON output

```bash
olef ui pin --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<digits>` | **Required.** Numeric PIN to enter. The value is never included in command output or diagnostics |
| `--no-submit` | Enter the digits without pressing Enter afterward |
| `--coordinate-fallback` | Explicitly allow center-coordinate injection when a digit label has no clickable ancestor |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui key

Press a named key or keycode

```bash
olef ui key --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<name>` | **Required.** |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui hide-keyboard

Hide the soft keyboard if Olef sees it; no-op when already hidden

```bash
olef ui hide-keyboard --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui back

Press the Back button

```bash
olef ui back --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui home

Press the Home button

```bash
olef ui home --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--allow-other-app` | In a session with --app: this step acts outside the app under test on purpose (share sheet, browser, settings), so skip the foreground guard |
| `--allow-crash` | In a session with --app: a crash or ANR of an app process during this step does not fail it |
| `--dismiss-system-ui` | In a session with --app: when system UI (notification shade, heads-up) covers the app, collapse it and retry once instead of failing. Recorded as a flake signal |
| `--if-screen <HASH>` | Only act if the screen still matches this screen_hash (from your last `ui dump`/`ui wait`). On mismatch the command fails with code=screen_changed and the fresh compact screen in `detail` — use that instead of re-dumping |
| `--if-interaction <INTERACTION_HASH>` | Only act if the actionable structure still matches this interaction hash. Unlike --if-screen, volatile display content is ignored |
| `--observe` | Include the post-action compact screen in this same response (saves the follow-up `ui dump` round-trip) |
| `--observe-delay-ms <MS>` | Required accessibility-event quiet period before the observed screen is considered stable, in milliseconds Default: `500`. |
| `--timeout-ms <MS>` | Overall deadline for stable observation and any --expect-* postcondition Default: `3000`. |
| `--expect-text <TEXT>` | Require a stable destination containing this visible text |
| `--expect-desc <DESCRIPTION>` | Require a stable destination containing this content description |
| `--expect-rid <RESOURCE_ID>` | Require a stable destination containing this resource id |
| `--expect-package <PACKAGE>` | Require this foreground package after the action |
| `--expect-activity <ACTIVITY>` | Require this foreground activity after the action |
| `--expect-exact` | Match the --expect-* value exactly (case-insensitive) instead of as a substring |
| `--full` | With a satisfied --expect-* postcondition, return the whole post-action screen instead of its summary (hashes, foreground app, top texts) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui wait

Wait for an element / activity / package to appear (or be --gone)

```bash
olef ui wait --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--text <TEXT>` | Wait for an element whose visible text matches (substring; --exact for full) |
| `--rid <RID>` | Wait for an element whose resource-id matches (substring) |
| `--desc <DESC>` | Wait for an element whose content-description matches (substring) |
| `--klass <KLASS>` | Wait for an element whose class name matches (substring) |
| `--activity <ACTIVITY>` | Wait until the foreground activity name contains this (substring) |
| `--package <PACKAGE>` | Wait until the foreground app's package contains this (e.g. `chrome`) |
| `--package-not <PACKAGE_NOT>` | Wait until the foreground app's package does NOT contain this — i.e. the screen left this app (a browser/dialer/share-sheet opened, or you navigated back out) |
| `--exact` | Match selector values (--text/--rid/--desc/--klass) exactly instead of as a case-insensitive substring |
| `--gone` | Invert: wait until the matched element is *gone* instead of present |
| `--checked <BOOL>` | With a selector: wait until the element is checked (`true`) or unchecked (`false`). A switch, checkbox, or Compose chip/toggle Values: `true`, `false`. |
| `--selected <BOOL>` | With a selector: wait until the element is selected (`true`) or not Values: `true`, `false`. |
| `--enabled <BOOL>` | With a selector: wait until the element is enabled (`true`) or disabled Values: `true`, `false`. |
| `--value <N>` | With a selector: wait until the element's range value (a slider or progress bar) is N, within half a step |
| `--has-text <TEXT>` | With a selector: wait until the element's own text contains this (normalized, case-insensitive). On timeout the error shows the text it had |
| `--timeout-ms <TIMEOUT_MS>` | Give up after this many milliseconds Default: `10000`. |
| `--timeout <DURATION>` | Give up after this long, with a unit: `30s`, `500ms`, `2m` Conflicts with: `timeout_ms`. |
| `--poll-ms <POLL_MS>` | How often to re-check, in milliseconds Default: `200`. |
| `--stable` | Wait until the screen stops changing: no accessibility events for --stable-ms, then the same tree (bounds included) one quiet period later. Alone it waits out animations and loading; with a selector it waits for the element, then for the screen around it to settle |
| `--stable-ms <STABLE_MS>` | Quiet period --stable requires, in milliseconds (50–2000) Default: `400`. |
| `--pixels` | With --stable, also require the pixels to hold still, which catches canvas, Lottie and video motion the accessibility tree does not show |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef ui toast

Capture recent toast messages: those shown in the last 30 s (including one raised by your previous action), else the first shown within --wait-ms. Each reports `age_ms`

```bash
olef ui toast --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--wait-ms <WAIT_MS>` | How long to wait for a toast when none was shown recently, in milliseconds Default: `5000`. |
| `--json` | Accepted for compatibility; output is always JSON. |