# olef debug

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

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 debug

Agent-first debug snapshots, timelines, replays, and debugger control

```bash
olef debug --help
```

Output: **json**.

### olef debug auto

Start an app, attach the debugger, and return a snapshot

```bash
olef debug auto --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<app_target>` | App alias, package, or installed app name. Defaults to config, then foreground app |
| `--app <APP>` | App alias or installed app name. Useful when the target would be parsed as an option |
| `--package <PACKAGE>` | Exact package/process name. Overrides target and --app |
| `--mode <MODE>` | Engines to attach: java (default), native, or mixed (both) Values: `auto`, `java`, `native`, `mixed`. |
| `--no-start` | Do not launch the app before attaching/snapshotting |
| `--no-attach` | Do not attach the debugger; only resolve, launch, and snapshot |
| `--from-start` | Start the app under the debugger so breakpoints catch startup code Conflicts with: `no_start`. |
| `--break <FILE:LINE>` | Line breakpoint set at attach, as FILE:LINE (repeatable) |
| `--break-exception <CLASS>` | Exception breakpoint set at attach (repeatable) |
| `--launch-activity <ACTIVITY>` | Activity to start with --from-start when the app has several launcher activities (`.Main` or a class name) |
| `--timeout-ms <TIMEOUT_MS>` | App foreground wait timeout after launch Default: `20000`. |
| `--logs <LOGS>` | Number of recent logcat lines to include Default: `200`. |
| `--depth <DEPTH>` | Include expanded top-frame variables when the debugger is suspended Default: `1`. |
| `--screenshot-dir <SCREENSHOT_DIR>` | Directory for screenshot artifacts |
| `--no-screenshot` | Skip screenshot capture |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug snapshot

Capture one bounded debug state object for an agent

```bash
olef debug snapshot --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package used for log/debugger filtering where possible |
| `--out <OUT>` / `-o` | Write the snapshot JSON to a file instead of stdout |
| `--screenshot-dir <SCREENSHOT_DIR>` | Directory for screenshot artifacts |
| `--no-screenshot` | Skip screenshot capture |
| `--logs <LOGS>` | Number of recent logcat lines to include Default: `200`. |
| `--depth <DEPTH>` | Include expanded top-frame variables when the debugger is suspended Default: `1`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug record

Record a JSONL debug timeline: screen/app/logcat/debugger/screenshot events

```bash
olef debug record --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--out <OUT>` / `-o` | **Required.** JSONL timeline path |
| `--duration-ms <DURATION_MS>` | Stop automatically after this many milliseconds. Omit to record until Ctrl-C |
| `--poll-ms <POLL_MS>` | Poll interval for screen/debugger snapshots Default: `500`. |
| `--app <APP>` | App package used for annotations and debugger filtering where possible |
| `--screenshot-dir <SCREENSHOT_DIR>` | Directory for screenshot artifacts. Defaults beside --out |
| `--no-screenshots` | Skip screenshot capture on screen changes |
| `--depth <DEPTH>` | Include expanded top-frame variables in debugger timeline events Default: `1`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug replay

Replay action events from a JSONL timeline

```bash
olef debug replay --help
```

Output: **jsonl**.

| Argument | Description |
| --- | --- |
| `<file>` | **Required.** JSONL timeline path |
| `--dry-run` | Print replayable actions without performing them |
| `--delay-ms <DELAY_MS>` | Fixed delay between replayed actions Default: `0`. |
| `--stop-on-error` | Stop at the first unsupported or failed action |
| `--repeat <REPEAT>` | Replay the whole timeline this many times back-to-back — a flake hunter Default: `1`. |
| `--diff` | After each action capture the post-action screen_hash and report run-to-run divergence — surfaces non-determinism in the underlying flow before it becomes a flaky test |
| `--settle-ms <SETTLE_MS>` | Settle delay before capturing screen_hash when --diff is set Default: `0`. |

### olef debug status

Show the debugger daemons and their sessions

```bash
olef debug status --help
```

Output: **json**.

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

### olef debug sessions

List attached debug sessions

```bash
olef debug sessions --help
```

Output: **json**.

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

### olef debug clients

List debuggable processes on the device and the sessions attached to them

```bash
olef debug clients --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--package <PACKAGE>` | Filter by app package/process |
| `--pid <PID>` | Filter by process id |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug attach

Attach the standalone debugger to a running app, or start it under the debugger

```bash
olef debug attach --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--package <PACKAGE>` | App package/process to attach to |
| `--pid <PID>` | Process id to attach to |
| `--mode <MODE>` | Engines to attach: java (default), native, or mixed (both) Values: `auto`, `java`, `native`, `mixed`. |
| `--wait-for-launch` | Restart the app under `am set-debug-app -w` and attach before its code runs |
| `--relaunch` | Restart an already running app under the debugger, carrying over the session's line and exception breakpoints: long stops then raise no ANR. Resets the app's state (force-stop) |
| `--break <FILE:LINE>` | Line breakpoint set at attach, as FILE:LINE (repeatable) |
| `--break-exception <CLASS>` | Exception breakpoint set at attach (repeatable) |
| `--break-function <NAME>` | Native function breakpoint set at attach (repeatable; native/mixed mode) |
| `--launch-timeout-ms <LAUNCH_TIMEOUT_MS>` | How long to wait for the launched process Default: `20000`. |
| `--launch-activity <ACTIVITY>` | Activity to start with --wait-for-launch (`.Main`, `pkg/.Main`, or a class name). Default: the only launcher activity, else the root of the app's most recent task, else the first launcher in manifest order |
| `--symbols <PATH>` | Unstripped libraries for native symbols: a directory of `.so` files, a directory with `<abi>/` subdirectories, or one file (repeatable). Gradle outputs under the project root are found automatically |
| `--signal-policy <SIGNAL_POLICY>` | `smart` (default) hands every signal to the app untouched (ART uses SIGSEGV and SIGBUS itself) and stops on real crashes at the faulting frame: a SIGSEGV ART does not own (at ART's `art_sigsegv_fault` hook), and SIGABRT, SIGILL, SIGFPE and SIGSYS; `stop` also stops on every SIGSEGV as it is raised, which can disturb ART (diagnosis only) Default: `smart`. Values: `smart`, `stop`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug break

Breakpoint commands

```bash
olef debug break --help
```

Output: **json**.

#### olef debug break line

Add a line breakpoint: Kotlin/Java, or C/C++ (`.c`, `.cpp`, `.h`, …) in a native or mixed session

```bash
olef debug break line --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--file <FILE>` | **Required.** Source file: a path, or a file name or path suffix found under the project root |
| `--line <LINE>` | **Required.** One-based source line number |
| `--disabled` | Create the breakpoint disabled |
| `--temporary` | Create a temporary breakpoint |
| `--condition <CONDITION>` | Breakpoint condition; the breakpoint stops only when it is true Conflicts with: `clear_condition`. |
| `--clear-condition` | Clear any condition on an existing breakpoint at this file/line |
| `--force` | Set the condition even if it does not parse (it then fails at each hit) |
| `--invoke` | Let the condition call app methods (runs app code) |
| `--variant <VARIANT>` | Locations on the line: all (default), outer method, or innermost lambda Values: `all`, `outer`, `lambda`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug break exception

Add a Java exception breakpoint

```bash
olef debug break exception --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<exception>` | **Required.** Fully-qualified exception class, e.g. java.lang.IllegalStateException |
| `--disabled` | Create the breakpoint disabled |
| `--caught <CAUGHT>` | Break on caught exceptions Default: `true`. Values: `true`, `false`. |
| `--uncaught <UNCAUGHT>` | Break on uncaught exceptions Default: `true`. Values: `true`, `false`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug break function

Add a native function breakpoint (C/C++ name, `ns::fn`, or a regex)

```bash
olef debug break function --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--name <NAME>` | **Required.** Function name: `checksum`, `fieldlab::checksum`, `Java_..._compute` |
| `--regex` | Treat --name as a regular expression |
| `--module <MODULE>` | Only in this library, e.g. `libfieldlab_native.so` |
| `--disabled` | Create the breakpoint disabled |
| `--temporary` | Remove the breakpoint after its first hit |
| `--condition <CONDITION>` | C/C++ condition; the breakpoint stops only when it is true |
| `--pass-count <PASS_COUNT>` | Skip this many hits before stopping |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug break address

Add a native breakpoint at a code address

```bash
olef debug break address --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--address <ADDRESS>` | **Required.** Address (hex `0x…` or decimal) |
| `--disabled` | Create the breakpoint disabled |
| `--temporary` | Remove the breakpoint after its first hit |
| `--condition <CONDITION>` | C/C++ condition; the breakpoint stops only when it is true |
| `--pass-count <PASS_COUNT>` | Skip this many hits before stopping |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug break data

Add a native data watchpoint: stop when memory is written (or read)

```bash
olef debug break data --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--expression <EXPRESSION>` | Variable in scope at the current stop, or a global, e.g. `g_counter` |
| `--address <ADDRESS>` | Watch this address instead of an expression's storage Conflicts with: `expression`. |
| `--size <SIZE>` | Bytes to watch (default: the expression's size; at most 8) |
| `--access <ACCESS>` | Access that stops: write (default), read, or read-write Default: `write`. Values: `write`, `read`, `read-write`. |
| `--disabled` | Create the breakpoint disabled |
| `--temporary` | Remove the breakpoint after its first hit |
| `--condition <CONDITION>` | C/C++ condition; the breakpoint stops only when it is true |
| `--pass-count <PASS_COUNT>` | Skip this many hits before stopping |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug break method

Add a Java/Kotlin wildcard method breakpoint

```bash
olef debug break method --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--class <CLASS>` | **Required.** Class name or pattern |
| `--method <METHOD>` | **Required.** Method name |
| `--disabled` | Create the breakpoint disabled |
| `--entry <ENTRY>` | Break on method entry Default: `true`. Values: `true`, `false`. |
| `--exit` | Break on method exit |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug break field

Add a Java/Kotlin field watchpoint at a source location

```bash
olef debug break field --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--file <FILE>` | **Required.** Source file containing the field (unused: the field is found by class and name) |
| `--line <LINE>` | **Required.** One-based source line number |
| `--class <CLASS>` | **Required.** Declaring class name |
| `--field <FIELD>` | **Required.** Field name |
| `--disabled` | Create the breakpoint disabled |
| `--temporary` | Create a temporary breakpoint |
| `--access` | Break on field access |
| `--modification <MODIFICATION>` | Break on field modification Default: `true`. Values: `true`, `false`. |
| `--accept-slowdown` | Use a real field watch, which slows the whole app |
| `--duration-ms <DURATION_MS>` | Auto-clear a field watch after this long Default: `60000`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug break update

Update a breakpoint by stable id. Native ids (nbp_...) support enabled, temporary, condition, clear-condition and pass-count; use `logpoint add` to create native logging breakpoints

```bash
olef debug break update --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--id <ID>` | **Required.** Breakpoint id from `debug breakpoints` |
| `--enabled <ENABLED>` | Enable or disable the breakpoint Values: `true`, `false`. |
| `--temporary <TEMPORARY>` | Mark breakpoint temporary or persistent Values: `true`, `false`. |
| `--condition <CONDITION>` | Breakpoint condition; the breakpoint stops only when it is true Conflicts with: `clear_condition`. |
| `--clear-condition` | Clear any breakpoint condition |
| `--log-expression <LOG_EXPRESSION>` | Log expression without stopping when suspend policy is `none` Conflicts with: `clear_log_expression`. |
| `--clear-log-expression` | Clear the log expression |
| `--log-message <LOG_MESSAGE>` | Toggle the default "breakpoint hit" log message Values: `true`, `false`. |
| `--log-stack <LOG_STACK>` | Toggle stack trace logging Values: `true`, `false`. |
| `--suspend <SUSPEND>` | Suspend policy: all, thread, or none Values: `all`, `thread`, `none`. |
| `--pass-count <PASS_COUNT>` | Pass count. Use 0 to disable pass-count filtering |
| `--force` | Set expressions even if they do not parse (they then fail at each hit) |
| `--invoke` | Let the condition and log expression call app methods (runs app code) |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug break remove

Remove a breakpoint by stable id

```bash
olef debug break remove --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--id <ID>` | **Required.** Breakpoint id from `debug breakpoints` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug logpoint

Non-suspending debugger logpoints and their structured hit stream

```bash
olef debug logpoint --help
```

Output: **json**.

#### olef debug logpoint add

Configure a non-suspending line logpoint (Kotlin/Java or C/C++)

```bash
olef debug logpoint add --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--file <FILE>` | **Required.** Source file: a path, or a file name or path suffix found under the project root |
| `--line <LINE>` | **Required.** One-based source line number |
| `--disabled` | Create the logpoint disabled |
| `--temporary` | Remove the logpoint after its first hit |
| `--expression <EXPRESSION>` | Expression whose rendered value is logged at each matching hit |
| `--log-message` | Include the default breakpoint-hit message (location and thread) |
| `--log-stack` | Include a stack trace in the logged message |
| `--condition <CONDITION>` | Boolean condition evaluated before logging |
| `--pass-count <PASS_COUNT>` | Log only after this many matching passes. Use 0 to disable filtering |
| `--force` | Set expressions even if they do not parse (they then fail at each hit) |
| `--owner <OWNER>` | Ownership label used for safe remove/clear operations Default: `olef`. |
| `--max-events-per-second <MAX_EVENTS_PER_SECOND>` | Maximum structured events captured per second for this logpoint |
| `--max-message-chars <MAX_MESSAGE_CHARS>` | Maximum rendered-message characters retained per structured event |
| `--invoke` | Let the expression and condition call app methods (runs app code) |
| `--variant <VARIANT>` | Locations on the line: all (default), outer method, or innermost lambda Values: `all`, `outer`, `lambda`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug logpoint list

List configured logpoints

```bash
olef debug logpoint list --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable debugger session id |
| `--id <BREAKPOINT_ID>` | Stable logpoint/breakpoint id |
| `--owner <OWNER>` | Ownership label to filter by |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug logpoint events

Read a bounded page of structured logpoint-hit events

```bash
olef debug logpoint events --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--after <AFTER>` | Return events strictly newer than this cursor |
| `--stream-id <STREAM_ID>` | Event-stream id that issued --after; both options must be supplied together |
| `--limit <LIMIT>` | Maximum number of events to return Default: `100`. |
| `--session <SESSION>` | Stable debugger session id |
| `--id <BREAKPOINT_ID>` | Stable logpoint/breakpoint id |
| `--owner <OWNER>` | Ownership label to filter by |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug logpoint follow

Follow structured logpoint-hit events as JSONL

```bash
olef debug logpoint follow --help
```

Output: **jsonl**.

| Argument | Description |
| --- | --- |
| `--after <AFTER>` | Resume strictly after this cursor instead of starting at the live tail Conflicts with: `replay_existing`. |
| `--stream-id <STREAM_ID>` | Event-stream id that issued --after; both options must be supplied together |
| `--limit <LIMIT>` | Maximum events requested from the daemon in one page Default: `100`. |
| `--poll-ms <POLL_MS>` | Maximum daemon long-poll wait in milliseconds Default: `1000`. |
| `--duration-ms <DURATION_MS>` | Stop after this many milliseconds. Omit to follow until Ctrl-C |
| `--max-events <MAX_EVENTS>` | Stop after emitting this many logpoint events |
| `--replay-existing` | Emit the current bounded event history before following new hits |
| `--session <SESSION>` | Stable debugger session id |
| `--id <BREAKPOINT_ID>` | Stable logpoint/breakpoint id |
| `--owner <OWNER>` | Ownership label to filter by |

#### olef debug logpoint remove

Remove one Olef-owned logpoint by stable id

```bash
olef debug logpoint remove --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--id <ID>` | **Required.** Stable id from `debug logpoint list` or `debug logpoint add` |
| `--owner <OWNER>` | Ownership label that must match the logpoint Default: `olef`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug logpoint clear

Remove Olef-owned logpoints matching the supplied scope

```bash
olef debug logpoint clear --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--owner <OWNER>` | Remove only logpoints with this ownership label Default: `olef`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug breakpoints

List the session's breakpoints

```bash
olef debug breakpoints --help
```

Output: **json**.

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

### olef debug pause

Pause the selected debug session

```bash
olef debug pause --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug resume

Resume the selected debug session

```bash
olef debug resume --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug step-in

Step into from the selected suspended session

```bash
olef debug step-in --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug step-over

Step over from the selected suspended session

```bash
olef debug step-over --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug step-out

Step out from the selected suspended session

```bash
olef debug step-out --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug stop

Detach the debugger and resume the app (same as detach)

```bash
olef debug stop --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug detach

Detach the debugger and resume the app

```bash
olef debug detach --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug stack

Print stack frames for the selected suspended session

```bash
olef debug stack --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--limit <LIMIT>` | Maximum number of frames per stack Default: `64`. |
| `--timeout-ms <TIMEOUT_MS>` | Debugger manager request timeout Default: `2500`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug threads

Print debugger threads and their stack frames

```bash
olef debug threads --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--limit <LIMIT>` | Maximum number of frames per stack Default: `64`. |
| `--timeout-ms <TIMEOUT_MS>` | Debugger manager request timeout Default: `2500`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug variables

Print visible variables for the selected suspended frame

```bash
olef debug variables --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Execution stack/thread index from `debug threads` |
| `--frame <FRAME>` | Frame index within the selected thread |
| `--depth <DEPTH>` | Object expansion depth. 0 prints only local values, 1 prints direct fields Default: `0`. |
| `--max-fields <MAX_FIELDS>` | Maximum instance fields to include per object Default: `64`. |
| `--max-array-items <MAX_ARRAY_ITEMS>` | Maximum array/list items to include per array Default: `32`. |
| `--timeout-ms <TIMEOUT_MS>` | Debugger manager request timeout Default: `2500`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug eval

Evaluate an expression in the selected frame

```bash
olef debug eval --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<expression>` | **Required.** Deterministic expression path: `this`, a local name, fields, and array indexes |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Execution stack/thread index from `debug threads` |
| `--frame <FRAME>` | Frame index within the selected thread |
| `--depth <DEPTH>` | Object expansion depth. 0 prints only the result value Default: `1`. |
| `--max-fields <MAX_FIELDS>` | Maximum instance fields to include per object Default: `64`. |
| `--max-array-items <MAX_ARRAY_ITEMS>` | Maximum array/list items to include per array Default: `32`. |
| `--timeout-ms <TIMEOUT_MS>` | Evaluation request timeout (bounds each method call with --invoke) Default: `5000`. |
| `--invoke` | Allow method calls and `toString()` rendering (runs app code) |
| `--max-message-chars <MAX_MESSAGE_CHARS>` | Maximum characters of string values and rendered `toString()` text Default: `4096`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug inspect

Inspect an expression or a previously returned object handle

```bash
olef debug inspect --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<expression>` | Deterministic expression path: `this`, a local name, fields, and array indexes Conflicts with: `handle`. |
| `--handle <HANDLE>` | Object handle returned by `debug variables`, `debug eval`, or `debug inspect` |
| `--path <PATH>` | Relative path from --handle, e.g. `.field[0]` |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Execution stack/thread index from `debug threads` |
| `--frame <FRAME>` | Frame index within the selected thread |
| `--depth <DEPTH>` | Object expansion depth. 0 prints only the result value Default: `1`. |
| `--max-fields <MAX_FIELDS>` | Maximum instance fields to include per object Default: `64`. |
| `--max-array-items <MAX_ARRAY_ITEMS>` | Maximum array/list items to include per array Default: `32`. |
| `--timeout-ms <TIMEOUT_MS>` | Inspection request timeout (bounds each method call with --invoke) Default: `5000`. |
| `--invoke` | Allow method calls and `toString()` rendering (runs app code) |
| `--max-message-chars <MAX_MESSAGE_CHARS>` | Maximum characters of string values and rendered `toString()` text Default: `4096`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug coroutines

Coroutine and async-state inspection for suspended sessions

```bash
olef debug coroutines --help
```

Output: **json**.

#### olef debug coroutines snapshot

Snapshot coroutine-like state reachable from suspended Java/Kotlin frames

```bash
olef debug coroutines snapshot --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--limit <LIMIT>` | Maximum threads/frames/continuations to include Default: `64`. |
| `--depth <DEPTH>` | Object expansion depth for spilled locals Default: `1`. |
| `--invoke` | Read each continuation's source line by calling its getStackTraceElement() (runs app code; needs a breakpoint or step stop) |
| `--timeout-ms <TIMEOUT_MS>` | Debugger manager request timeout Default: `2500`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug coroutines threads

Print debugger threads with dispatcher hints

```bash
olef debug coroutines threads --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--limit <LIMIT>` | Maximum threads to include Default: `32`. |
| `--timeout-ms <TIMEOUT_MS>` | Debugger manager request timeout Default: `2500`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug coroutines continuation

Inspect continuation-like objects in the selected frame

```bash
olef debug coroutines continuation --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Execution stack/thread index from `debug threads` |
| `--frame <FRAME>` | Frame index within the selected thread |
| `--depth <DEPTH>` | Object expansion depth for spilled locals Default: `2`. |
| `--timeout-ms <TIMEOUT_MS>` | Debugger manager request timeout Default: `2500`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug coroutines flow

Inspect a Flow/StateFlow-like expression without collecting or invoking methods

```bash
olef debug coroutines flow --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--expr <EXPR>` | **Required.** Deterministic expression path to a Flow/StateFlow-like object |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Execution stack/thread index from `debug threads` |
| `--frame <FRAME>` | Frame index within the selected thread |
| `--depth <DEPTH>` | Object expansion depth Default: `2`. |
| `--timeout-ms <TIMEOUT_MS>` | Debugger manager request timeout Default: `2500`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug continue-until

Resume until a source location (and optional condition) is reached

```bash
olef debug continue-until --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--file <FILE>` | Source file path to match against the top frame. Unless a breakpoint already exists at --file:--line, a temporary one is set there for the run and removed afterwards |
| `--line <LINE>` | One-based source line to match against the top frame |
| `--condition <CONDITION>` | Deterministic JDI path expression that must evaluate to true/non-null/non-zero |
| `--timeout-ms <TIMEOUT_MS>` | Stop waiting after this many milliseconds Default: `10000`. |
| `--poll-ms <POLL_MS>` | Poll interval while waiting Default: `100`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug watch

Watch expression commands

```bash
olef debug watch --help
```

Output: **json**.

#### olef debug watch add

Add or replace a watch expression

```bash
olef debug watch add --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<expression>` | **Required.** |
| `--name <NAME>` | Optional stable name. Defaults to the expression text |
| `--invoke` | Allow method calls in the watch (runs app code on every breakpoint or step stop) |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug watch list

List watches and evaluate them if a session is suspended

```bash
olef debug watch list --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--depth <DEPTH>` | Object expansion depth for evaluated watch values Default: `1`. |
| `--max-fields <MAX_FIELDS>` | Maximum instance fields to include per object Default: `64`. |
| `--max-array-items <MAX_ARRAY_ITEMS>` | Maximum array/list items to include per array Default: `32`. |
| `--timeout-ms <TIMEOUT_MS>` | Debugger manager request timeout Default: `2500`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug watch remove

Remove a watch by id

```bash
olef debug watch remove --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--id <ID>` | **Required.** Id of the watch to remove (from `debug watch list`) |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug watch clear

Remove all watches

```bash
olef debug watch clear --help
```

Output: **json**.

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

### olef debug native

Native (C/C++) debugging: readiness, registers, memory, disassembly, modules, symbols, and instruction stepping

```bash
olef debug native --help
```

Output: **json**.

#### olef debug native status

What native debugging of an app needs (NDK, lldb-server for its ABI, debuggability, local symbols) and the native artifacts on the device

```bash
olef debug native status --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<app_target>` | App alias or package. Defaults to config |
| `--app <APP>` | App alias or installed package |
| `--package <PACKAGE>` | Exact package/process name. Overrides target and --app |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug native registers

Registers of the selected frame (general purpose by default)

```bash
olef debug native registers --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Thread index, tid, or name from `debug threads` |
| `--frame <FRAME>` | Frame index within the selected thread |
| `--set <SET>` | Register set name (substring), e.g. `floating`; default general purpose |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug native memory

Read memory as a hex/ASCII dump

```bash
olef debug native memory --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Thread index, tid, or name from `debug threads` |
| `--frame <FRAME>` | Frame index within the selected thread |
| `--address <ADDRESS>` | Start address (hex `0x…` or decimal) |
| `--expression <EXPRESSION>` | Pointer or register value (e.g. '$pc') to read from; for a non-pointer variable, read the object's storage. Cast integer addresses to void* |
| `--count <COUNT>` | Bytes to read (at most 4096) Default: `64`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug native disassemble

Disassemble around the current pc, a function, or an address

```bash
olef debug native disassemble --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Thread index, tid, or name from `debug threads` |
| `--frame <FRAME>` | Frame index within the selected thread |
| `--function <FUNCTION>` | Disassemble this function instead of the current frame Conflicts with: `address`. |
| `--address <ADDRESS>` | Disassemble from this address instead of the current frame |
| `--count <COUNT>` | Instructions to show (at most 512) Default: `32`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug native modules

Loaded libraries: load address, build-id, and whether symbols are loaded

```bash
olef debug native modules --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--all` | Include system libraries, not only the app's |
| `--filter <FILTER>` | Only modules whose name contains this text |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug native symbols

Load symbols from an unstripped library into the session

```bash
olef debug native symbols --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<path>` | **Required.** Unstripped library to load symbols from |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug native step-instruction

Step one machine instruction (`--over` steps over calls)

```bash
olef debug native step-instruction --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--thread <THREAD>` | Thread index, tid, or name |
| `--over` | Step over calls instead of into them |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug step-until-screen-change

Step over until the screen hash changes, then return a final snapshot

```bash
olef debug step-until-screen-change --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--timeout-ms <TIMEOUT_MS>` | Stop waiting after this many milliseconds Default: `10000`. |
| `--poll-ms <POLL_MS>` | Poll interval while waiting Default: `100`. |
| `--app <APP>` | App package used for the final snapshot |
| `--depth <DEPTH>` | Include expanded top-frame variables in the final snapshot Default: `1`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug step-until-log

Step over until logcat emits a matching line, then return a final snapshot

```bash
olef debug step-until-log --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--pattern <PATTERN>` | **Required.** Substring that must appear in a logcat line |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--timeout-ms <TIMEOUT_MS>` | Stop waiting after this many milliseconds Default: `10000`. |
| `--poll-ms <POLL_MS>` | Poll interval while waiting Default: `100`. |
| `--app <APP>` | App package used for the final snapshot |
| `--depth <DEPTH>` | Include expanded top-frame variables in the final snapshot Default: `1`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug run-until-crash

Resume and wait for a Java/native crash or ANR, then return a final snapshot. The device is released while waiting, so other commands can trigger it

```bash
olef debug run-until-crash --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--session <SESSION>` | Stable session id (preferred) or current index from `debug sessions` |
| `--timeout-ms <TIMEOUT_MS>` | Stop waiting after this many milliseconds Default: `30000`. |
| `--app <APP>` | App package used for the final snapshot |
| `--logs <LOGS>` | Number of recent logcat lines to include in the final snapshot/bundle Default: `120`. |
| `--depth <DEPTH>` | Include expanded top-frame variables in the final snapshot Default: `1`. |
| `--out <OUT>` / `-o` | Write the result JSON to a file instead of stdout |
| `--bundle <BUNDLE>` | Also write a local crash bundle to this directory |
| `--native-artifacts` | Collect best-effort ANR/tombstone artifacts when available |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef debug tombstones

List or pull native tombstone files from the device

```bash
olef debug tombstones --help
```

Output: **json**.

#### olef debug tombstones list

List recent native tombstone files visible through adb

```bash
olef debug tombstones list --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App alias/package label for output context |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef debug tombstones pull

Pull recent native tombstone files into a local directory

```bash
olef debug tombstones pull --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--out <OUT>` / `-o` | **Required.** Output directory |
| `--app <APP>` | App alias/package label for output context |
| `--json` | Accepted for compatibility; output is always JSON. |