# olef app

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

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 app

Application lifecycle, info, and install rituals

```bash
olef app --help
```

Output: **json**.

### olef app start

Launch the app's default activity, or an explicit activity with --activity

```bash
olef app start --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<package>` | App package, app alias from config, or installed package name |
| `--activity <ACTIVITY>` | Explicit activity class to launch, e.g. .MainActivity or com.example.MainActivity |
| `--timeout-ms <MS>` | How long to wait for the activity to reach the foreground (default 15000; raise it for slow devices or apps with heavy startup) |
| `--json` | Accepted for compatibility; output is always JSON. |

Examples from the CLI (replace sample packages, selectors, and paths with your own):

```bash
olef app start com.example.app --activity .MainActivity
```

### olef app stop

Force-stop the app

```bash
olef app stop --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<package>` | App package, app alias from config, or installed package name |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef app install

Install an APK and run the app-under-test setup ritual (clear/grant/launch/wait)

```bash
olef app install --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<app_apk>` | **Required.** Path to the APK to install |
| `--package <PACKAGE>` | Override the package name (otherwise read from the APK via aapt2) |
| `--clear` | Wipe app data after installing |
| `--grant-all` | Grant every runtime permission the app declares |
| `--grant <GRANT>` | Grant a specific runtime permission (repeatable) |
| `--launch` | Launch the app after installing |
| `--wait-front` | Launch and wait for the app to reach the foreground (implies --launch) |
| `--timeout-ms <TIMEOUT_MS>` | Timeout for --wait-front, in milliseconds Default: `20000`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef app apply

Build and get the current source onto the device the cheapest correct way: redefine + recompose in place, restart the activity, or reinstall; reports what it did, when the change takes effect and why

```bash
olef app apply --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--module <MODULE>` | Gradle application module (`app`, or a nested path like `apps:phone`). Default: `module` in the config, else `app` |
| `--variant <VARIANT>` | Build variant. Default: `variant` in the config, else `debug` |
| `--mode <MODE>` | `auto` applies in place when possible; `reinstall` always reinstalls Default: `auto`. Values: `auto`, `reinstall`. |
| `--at-least <AT_LEAST>` | Apply at least this strongly, e.g. `restart-activity` when a value is cached somewhere the analysis cannot see Values: `hot`, `restart-activity`, `reinstall`. |
| `--timeout-ms <TIMEOUT_MS>` | Cooperative apply budget, including Gradle and reads. Dispatched app mutations finish and record their baseline even if the budget expires Default: `1800000`. |
| `--no-screen` | Leave out `screen` (what changed in the UI structure after the change: app, texts that appeared or went away), which costs two UI reads |
| `--fresh-viewmodels` | Restart the activity with its ViewModels cleared, so what they computed is computed again (implies `--at-least restart-activity`). For a value a ViewModel cached, which a plain restart keeps |
| `--prepare` | Build what the next apply builds, without the device, so its Gradle and Kotlin daemons, configuration cache entry and D8 are warm: a cloud session runs it while the emulator boots. Changes nothing on the device |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef app reinstall

Like `install`, but uninstall any existing copy first

```bash
olef app reinstall --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<app_apk>` | **Required.** Path to the APK to install |
| `--package <PACKAGE>` | Override the package name (otherwise read from the APK via aapt2) |
| `--clear` | Wipe app data after installing |
| `--grant-all` | Grant every runtime permission the app declares |
| `--grant <GRANT>` | Grant a specific runtime permission (repeatable) |
| `--launch` | Launch the app after installing |
| `--wait-front` | Launch and wait for the app to reach the foreground (implies --launch) |
| `--timeout-ms <TIMEOUT_MS>` | Timeout for --wait-front, in milliseconds Default: `20000`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef app state

Snapshot, restore, recover, and clean up private debuggable-app state

```bash
olef app state --help
```

Output: **json**.

#### olef app state snapshot

Snapshot selected private debuggable-app paths into a protected host directory

```bash
olef app state snapshot --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package or configured app alias. Defaults through normal app resolution |
| `--out <OUT>` | **Required.** New snapshot directory. Existing paths are refused |
| `--include <INCLUDE>` | **Required.** Private relative file/directory to include; repeat for multiple roots |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef app state restore

Restore a snapshot transactionally, retaining private rollback data until verification

```bash
olef app state restore --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | Target app package or configured app alias. Defaults to the manifest package |
| `--from <FROM>` | **Required.** Snapshot directory containing manifest.json and data/ |
| `--allow-incompatible` | Override package/signature compatibility refusal. This is unsafe and explicit |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef app state recover

Resolve an interrupted restore by rolling back unverified state or finalizing verified state

```bash
olef app state recover --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package or configured app alias. Defaults through normal app resolution |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef app state cleanup

Best-effort overwrite and delete of a protected host snapshot directory

```bash
olef app state cleanup --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--from <FROM>` | **Required.** Snapshot directory to securely clean up |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef app clear

Clear the app's data

```bash
olef app clear --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<package>` | App package, app alias from config, or installed package name |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef app info

Version name/code + label

```bash
olef app info --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<package>` | App package, app alias from config, or installed package name |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef app wait

Wait for the app to launch (or, with --front, reach the foreground)

```bash
olef app wait --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<package>` | App package, app alias from config, or installed package name |
| `--timeout-ms <TIMEOUT_MS>` | Give up after this many milliseconds Default: `20000`. |
| `--timeout <DURATION>` | Give up after this long, with a unit: `30s`, `500ms`, `2m` Conflicts with: `timeout_ms`. |
| `--front` | Wait until the app reaches the foreground, not just until it launches |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef app current

Print the current foreground app (package / activity / pid)

```bash
olef app current --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--json` | Accepted for consistency with other subcommands; output is always JSON |