# olef fault

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

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 fault

Put the device or app into a failure condition on purpose — process death, no network, full storage, a moved clock, failing backend calls — and undo it reliably. Start with `fault kinds`

```bash
olef fault --help
```

Output: **json**.

### olef fault kinds

List every fault kind: what it does, whether it is a one-off action or a state `fault clear` undoes, and what it needs. No device required

```bash
olef fault kinds --help
```

Output: **json**.

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

### olef fault inject

Inject a fault. A state fault stays until `fault clear` or `--duration-ms`; an action fault happens once. Replies with the fault record, including its id and how it will be undone

```bash
olef fault inject --help
```

Output: **json**.

#### olef fault inject process-death

Background the app and kill its process as Android does under memory pressure; its task stays in recents so reopening restores saved state

```bash
olef fault inject process-death --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package. Defaults to the configured app |
| `--relaunch` | Reopen the app afterwards like tapping its icon, then report the new pid |
| `--timeout-ms <TIMEOUT_MS>` | How long to wait for Android to let the backgrounded process be killed Default: `10000`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject dont-keep-activities

Destroy activities as soon as the user leaves them

```bash
olef fault inject dont-keep-activities --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject low-memory

Deliver an onTrimMemory level to the app

```bash
olef fault inject low-memory --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package. Defaults to the configured app |
| `--level <LEVEL>` | running-* levels need the app in the foreground; the others in the background Default: `running-critical`. Values: `running-moderate`, `running-low`, `running-critical`, `ui-hidden`, `background`, `moderate`, `complete`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject revoke-permission

Revoke a granted runtime permission (Android kills the app)

```bash
olef fault inject revoke-permission --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package. Defaults to the configured app |
| `--permission <PERMISSION>` | **Required.** Permission name, e.g. android.permission.CAMERA |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject orientation

Lock the screen rotation

```bash
olef fault inject orientation --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--rotation <ROTATION>` | **Required.** Values: `0`, `90`, `180`, `270`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject night-mode

Switch the system dark theme

```bash
olef fault inject night-mode --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--mode <MODE>` | Default: `on`. Values: `on`, `off`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject font-scale

Change the system font scale

```bash
olef fault inject font-scale --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--scale <SCALE>` | **Required.** Font scale, 0.5-3.0 (1.0 is the default size) |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject display-size

Override the display size and/or density

```bash
olef fault inject display-size --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--size <SIZE>` | Size as WIDTHxHEIGHT pixels, e.g. 1080x1200 |
| `--density <DENSITY>` | Density in dpi, e.g. 320 |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject app-locale

Set the app's own locale (per-app language)

```bash
olef fault inject app-locale --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package. Defaults to the configured app |
| `--locales <LOCALES>` | **Required.** Language tags separated by commas, e.g. ar-EG or he,en-US |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject split-screen

Shrink the app's task to part of the screen, as split screen does

```bash
olef fault inject split-screen --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package. Defaults to the configured app |
| `--percent <PERCENT>` | Share of the screen height the app keeps, 20-80 Default: `50`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject pip

Leave the app (HOME) so it can enter picture-in-picture; reports whether it did

```bash
olef fault inject pip --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package. Defaults to the configured app |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject doze

Force the device into deep Doze

```bash
olef fault inject doze --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject standby-bucket

Move the app to an App Standby bucket

```bash
olef fault inject standby-bucket --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--app <APP>` | App package. Defaults to the configured app |
| `--bucket <BUCKET>` | **Required.** Values: `active`, `working-set`, `frequent`, `rare`, `restricted`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject battery

Report the battery as unplugged, optionally low and with Battery Saver

```bash
olef fault inject battery --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--level <LEVEL>` | Battery level percent, 0-100 (default: keep the current level) |
| `--saver` | Also turn Battery Saver on |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject thermal

Report a thermal (overheating) status

```bash
olef fault inject thermal --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--status <STATUS>` | **Required.** Values: `light`, `moderate`, `severe`, `critical`, `emergency`, `shutdown`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject storage-full

Fill the data partition until only --free-mb remains

```bash
olef fault inject storage-full --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--free-mb <FREE_MB>` | Space left free, in MiB Default: `50`. |
| `--allow-physical` | Allow this on a physical device (other apps run out of space too) |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject clock

Move the system clock

```bash
olef fault inject clock --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--offset-ms <OFFSET_MS>` | **Required.** Milliseconds to move the clock; negative moves it back |
| `--allow-physical` | Allow this on a physical device (turns automatic time off until clear) |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject timezone

Change the system time zone

```bash
olef fault inject timezone --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--tz <TZ>` | **Required.** Olson time zone id, e.g. Asia/Tokyo |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject cpu-load

Keep CPU cores busy

```bash
olef fault inject cpu-load --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--threads <THREADS>` | Busy loops to run (default: one per CPU core) |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject airplane-mode

Turn airplane mode on

```bash
olef fault inject airplane-mode --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject wifi-off

Turn Wi-Fi off

```bash
olef fault inject wifi-off --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject mobile-data-off

Turn mobile data off

```bash
olef fault inject mobile-data-off --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject network-flap

Toggle airplane mode on and off repeatedly

```bash
olef fault inject network-flap --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--period-ms <PERIOD_MS>` | Time spent in each state, in milliseconds Default: `5000`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject dns-failure

Make every DNS lookup fail

```bash
olef fault inject dns-failure --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject network-speed

Throttle the emulator link to a cellular speed (emulator only)

```bash
olef fault inject network-speed --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--profile <PROFILE>` | **Required.** Values: `gsm`, `gprs`, `edge`, `umts`, `hsdpa`, `lte`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject network-latency

Add cellular latency to the emulator link (emulator only)

```bash
olef fault inject network-latency --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--profile <PROFILE>` | **Required.** Values: `gprs`, `edge`, `umts`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject http-errors

Answer matching proxied requests with an HTTP error (needs `net start`)

```bash
olef fault inject http-errors --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--host <HOST>` | Only requests whose host contains this text |
| `--path <PATH>` | Only requests whose path contains this text |
| `--percent <PERCENT>` | Share of matching requests hit, 1-100 Default: `100`. |
| `--seed <SEED>` | Seed for which requests are hit when --percent is below 100: the same seed hits the same requests in the same order Default: `0`. |
| `--status <STATUS>` | HTTP status to answer with Default: `503`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject http-latency

Delay matching proxied requests (needs `net start`)

```bash
olef fault inject http-latency --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--host <HOST>` | Only requests whose host contains this text |
| `--path <PATH>` | Only requests whose path contains this text |
| `--percent <PERCENT>` | Share of matching requests hit, 1-100 Default: `100`. |
| `--seed <SEED>` | Seed for which requests are hit when --percent is below 100: the same seed hits the same requests in the same order Default: `0`. |
| `--delay-ms <DELAY_MS>` | **Required.** Delay in milliseconds |
| `--jitter-ms <JITTER_MS>` | Extra random delay up to this many milliseconds (seeded by --seed) Default: `0`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject bandwidth

Stream matching proxied responses at a limited rate (needs `net start`)

```bash
olef fault inject bandwidth --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--host <HOST>` | Only requests whose host contains this text |
| `--path <PATH>` | Only requests whose path contains this text |
| `--percent <PERCENT>` | Share of matching requests hit, 1-100 Default: `100`. |
| `--seed <SEED>` | Seed for which requests are hit when --percent is below 100: the same seed hits the same requests in the same order Default: `0`. |
| `--bytes-per-sec <BYTES_PER_SEC>` | **Required.** Bytes per second delivered to the app |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject connection-reset

Break matching proxied responses partway through (needs `net start`)

```bash
olef fault inject connection-reset --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--host <HOST>` | Only requests whose host contains this text |
| `--path <PATH>` | Only requests whose path contains this text |
| `--percent <PERCENT>` | Share of matching requests hit, 1-100 Default: `100`. |
| `--seed <SEED>` | Seed for which requests are hit when --percent is below 100: the same seed hits the same requests in the same order Default: `0`. |
| `--after-bytes <AFTER_BYTES>` | Response body bytes delivered before the connection breaks Default: `0`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject truncated-response

Deliver only the start of matching proxied response bodies as if complete (needs `net start`)

```bash
olef fault inject truncated-response --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--host <HOST>` | Only requests whose host contains this text |
| `--path <PATH>` | Only requests whose path contains this text |
| `--percent <PERCENT>` | Share of matching requests hit, 1-100 Default: `100`. |
| `--seed <SEED>` | Seed for which requests are hit when --percent is below 100: the same seed hits the same requests in the same order Default: `0`. |
| `--keep-bytes <KEEP_BYTES>` | Response body bytes kept Default: `16`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject tls-failure

Fail the TLS handshake for matching HTTPS hosts (needs `net start`)

```bash
olef fault inject tls-failure --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--host <HOST>` | **Required.** Hosts containing this text fail their TLS handshake |
| `--percent <PERCENT>` | Share of connections that fail, 1-100 Default: `100`. |
| `--seed <SEED>` | Seed for which connections fail when --percent is below 100 Default: `0`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject incoming-call

Ring an incoming phone call (emulator only)

```bash
olef fault inject incoming-call --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--number <NUMBER>` | Caller number Default: `5551234`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject sms

Deliver an incoming SMS (emulator only)

```bash
olef fault inject sms --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--from <FROM>` | Sender number Default: `5551234`. |
| `--text <TEXT>` | **Required.** Message text |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject screen-off

Turn the screen off

```bash
olef fault inject screen-off --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject notification-shade

Pull the notification shade or quick settings down over the app

```bash
olef fault inject notification-shade --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--panel <PANEL>` | Default: `notifications`. Values: `notifications`, `quick-settings`. |
| `--duration-ms <DURATION_MS>` | Clear the fault automatically after this many milliseconds. Without it the fault stays until `fault clear` |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault inject emulator-crash

Crash the emulator (emulator only)

```bash
olef fault inject emulator-crash --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--relaunch` | Boot the emulator again afterwards |
| `--cold-boot` | With --relaunch, cold boot instead of loading the quick-boot snapshot |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef fault list

List the faults active on the device, oldest first

```bash
olef fault list --help
```

Output: **json**.

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

### olef fault clear

Undo faults and verify each restore. Newest first with --all

```bash
olef fault clear --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<ids>` | Fault ids from `fault inject` or `fault list` |
| `--all` | Clear every fault active on the device |
| `--expired` | Set by the --duration-ms timer: an id that is already gone is not an error |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef fault snapshot

Emulator snapshots: save a known state before a fault run, load it back after

```bash
olef fault snapshot --help
```

Output: **json**.

#### olef fault snapshot save

Save the emulator's current state under a name

```bash
olef fault snapshot save --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<name>` | **Required.** |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault snapshot load

Load a saved state (the app and Olef server restart with it)

```bash
olef fault snapshot load --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<name>` | **Required.** |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef fault snapshot list

List saved snapshots

```bash
olef fault snapshot list --help
```

Output: **json**.

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

#### olef fault snapshot delete

Delete a saved snapshot

```bash
olef fault snapshot delete --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<name>` | **Required.** |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef fault run

Run a JSON scenario: a sequence of Olef commands, faults, waits and checks. Every fault it injected is cleared at the end, pass or fail

```bash
olef fault run --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<file>` | **Required.** Scenario JSON file (see `commands --guide faults`) |
| `--seed <SEED>` | Seed for `pick` steps and proxy faults without their own --seed; the same seed replays the same choices. Overrides the file's `seed` |
| `--step-timeout-ms <MS>` | Stop a step that runs longer than this; the step fails and the scenario's faults are still cleared Default: `600000`. |
| `--json` | Accepted for compatibility; output is always JSON. |