# olef session Source: https://olef.dev/docs/reference/cli/session 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 session Reserve devices for drivers and provide passive observations to advisers ```bash olef session --help ``` Output: **json**. Examples from the CLI (replace sample packages, selectors, and paths with your own): ```bash olef --device emulator-5554 session open --agent driver-a olef --device emulator-5554 session observe --subscription adviser-b ``` ### olef session open Reserve an online device across commands, in one command: it observes the device for the new driver, applies settings and starting state, and keeps a journal. Opened by a caller that already holds the reservation, it nests: own settings, folder and cleanup on the shared reservation. Ownership has no automatic expiry ```bash olef session open --help ``` Output: **json**. | Argument | Description | | --- | --- | | `--agent ` | **Required.** Human-readable agent identity (not an authentication credential) | | `--token-out ` | Write the driver token to a new private file instead of stdout. Required with --redact; reuse it with --session-file | | `--app ` | The app under test (package or configured alias): turns on the foreground, crash and covered-screen guards, and is the default package for starting-state flags | | `--wait-ms ` | How long later actions wait for their target to appear, be unique and enabled (actions that support a target wait) Default: `10000`. | | `--timeout-ms ` | How long later `--expect-*` checks and `ui wait` wait, unless the command sets its own --timeout-ms Default: `10000`. | | `--pace-ms ` | Minimum gap between commands, for slow devices or demos. Never needed for correctness; reported as a flake signal when set Default: `0`. | | `--capture ` | Evidence per command: `steps` saves screens and a screenshot around every action; `failures` only when one fails; `off` none. Default: `failures` under `olef test run`, else `steps` Values: `steps`, `failures`, `off`. | | `--no-journal` | Do not keep the session journal (no journal, screens or failure reports) | | `--run-dir ` | Folder for the journal, screens, failure reports and report.html. Default: $OLEF_RUN_DIR under `test run`, else `.olef/sessions//` | | `--allow-crash` | A crash of an app process does not fail a step in this session | | `--no-preflight` | Skip the preflight checks (system UI in front, a foreign http_proxy, clock skew, leftover notifications) | | `--clear-data` | Start from a fresh install's state: clear the app's data | | `--reset-permissions` | Return every runtime permission to its fresh-install state (not granted, and asking again even after "don't ask again"), so the app's permission dialogs appear as on a first run. Not restored at close | | `--grant ` | Grant this runtime permission to the app at open; restored at close | | `--revoke ` | Revoke this runtime permission at open; restored at close | | `--deny ` | Deny this runtime permission with "don't ask again" at open (revoked, user-set and user-fixed), so the app's dialog for it never shows; restored at close | | `--reset-permission ` | Return this one runtime permission to its fresh-install state (not granted, asking again), so its dialog appears as on a first run. Not restored at close | | `--profile ` | Apply a display profile preset (`automation`: animations off); restored at close | | `--launch ` | Launch the app at open, optionally at this activity (`.MainActivity`) | | `--expect-text ` | With --launch: wait until this text is on screen | | `--expect-rid ` | With --launch: wait until this resource id or test tag is on screen | | `--json` | Accepted for compatibility; output is always JSON. | Examples from the CLI (replace sample packages, selectors, and paths with your own): ```bash olef session open --agent explorer --token-out session.token --app io.github.andriyo.shadowdroid.sample --launch .MainActivity --expect-rid status_text ``` ### olef session status Read owner and interrupted-operation metadata without changing ownership ```bash olef session status --help ``` Output: **json**. | Argument | Description | | --- | --- | | `--json` | Accepted for compatibility; output is always JSON. | Examples from the CLI (replace sample packages, selectors, and paths with your own): ```bash olef --device emulator-5554 session open --agent driver-a olef --device emulator-5554 session observe --subscription adviser-b ``` ### olef session close Undo the session's starting state, write its summary and report.html, and release the reservation (or return to the outer session when nested). Stop its proxy/recorder first. A token file that was never written closes nothing, so a script can arm its trap before opening ```bash olef session close --help ``` Output: **json**. | Argument | Description | | --- | --- | | `--exit-code ` | The script's exit status (`$?` in a trap): 0 marks the run passed | | `--json` | Accepted for compatibility; output is always JSON. | Examples from the CLI (replace sample packages, selectors, and paths with your own): ```bash olef --session-file session.token session close --exit-code 0 ``` ### olef session recover Clear an interrupted operation: on the same boot when it was only server UI input and that server is idle or gone, otherwise after a verified device reboot and external-worker review ```bash olef session recover --help ``` Output: **json**. | Argument | Description | | --- | --- | | `--external-workers-stopped` | Attest that all external test/build/ADB workers from the interrupted command are stopped | | `--json` | Accepted for compatibility; output is always JSON. | Examples from the CLI (replace sample packages, selectors, and paths with your own): ```bash olef --device emulator-5554 session open --agent driver-a olef --device emulator-5554 session observe --subscription adviser-b ``` ### olef session handoff Transfer an idle device, revoking the old token; retain a handoff context artifact ```bash olef session handoff --help ``` Output: **json**. | Argument | Description | | --- | --- | | `--agent ` | **Required.** | | `--context ` | **Required.** Path to a JSON file (an object, at most 1 MiB) with candidate, plan, backend and starting-state references | | `--token-out ` | Write the recipient's token to a new private file instead of stdout. Required with --redact; reuse it with --session-file | | `--json` | Accepted for compatibility; output is always JSON. | Examples from the CLI (replace sample packages, selectors, and paths with your own): ```bash olef --device emulator-5554 session open --agent driver-a olef --device emulator-5554 session observe --subscription adviser-b ``` ### olef session observe Observe existing UI and independently consume crashes; never installs or reconnects ```bash olef session observe --help ``` Output: **json**. | Argument | Description | | --- | --- | | `--subscription ` | **Required.** Independent event consumer ID; use a different ID for each adviser | | `--json` | Accepted for compatibility; output is always JSON. | Examples from the CLI (replace sample packages, selectors, and paths with your own): ```bash olef --device emulator-5554 session open --agent driver-a olef --device emulator-5554 session observe --subscription adviser-b ```