# olef net

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

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 net

Network MITM proxy: enable, inspect, intercept, and modify HTTP(S) traffic

```bash
olef net --help
```

Output: **json**.

### olef net check

Verdict: is this app interceptable (debuggable, NSC trusts user CA, engine proxy-aware)?

```bash
olef net check --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<package>` | App package, app alias from config, or installed package name |
| `--probe` | Launch a package-scoped HTTPS canary and wait for its exact decrypted request. The app must handle the canary VIEW intent and issue that URL itself |
| `--probe-timeout-ms <PROBE_TIMEOUT_MS>` | How long to wait for the canary request, in milliseconds Default: `10000`. |
| `--fresh` | Ignore `proxy.ca_trusted` and the verify-once cache; probe the device |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net trust

Install / trust the Olef CA on the device

```bash
olef net trust --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--auto` | Choose the best available install path for this device (default) |
| `--system` | Push into the system trust store (emulator/root) |
| `--push` | Stage the CA in Downloads and open Settings for manual installation. A device screen-lock credential is required to finish the install |
| `--ui` | Legacy alias for --push. This does not automate certificate install Conflicts with: `push`. |
| `--fresh` | Ignore `proxy.ca_trusted` and the verify-once cache; install/verify against the device for real |
| `--no-adb-root` | Never restart adbd as root. By default a debuggable build (an emulator's google_apis image) is switched to a root adbd so the CA can go into the system store; that briefly drops adb forwards |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net ca

Manage the proxy's signing CA (use your own, inspect it, or regenerate)

```bash
olef net ca --help
```

Output: **json**.

#### olef net ca import

Install a user-provided CA as the proxy's signing CA (replaces the auto-generated one). Everything downstream — `net trust`, `net check`, leaf signing — then uses your CA. Re-run `net trust` after importing so the device trusts the new CA, and restart the proxy if it's running

```bash
olef net ca import --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--cert <PATH>` | **Required.** PEM certificate file (your root/intermediate CA). May also contain the private key (a combined PEM like mitmproxy's `mitmproxy-ca.pem`) |
| `--key <PATH>` | PEM private key file. Omit if the key is in the --cert file. PKCS#1 / SEC1 keys are converted to PKCS#8 via openssl automatically |
| `--project` | Operate on the per-project CA (`<project>/.olef/ca.*`) Conflicts with: `global`. |
| `--global` | Operate on the global CA (`~/.olef/net/ca.*`) Conflicts with: `project`. |
| `--json` | Accepted for compatibility; output is always JSON. |

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

```bash
olef net ca import --cert mitmproxy-ca.pem
olef net ca import --cert corp-ca.crt --key corp-ca.key
```

#### olef net ca info

Show the current signing CA: source, subject, validity, key type, and the Android trust-store hash

```bash
olef net ca info --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--project` | Operate on the per-project CA (`<project>/.olef/ca.*`) Conflicts with: `global`. |
| `--global` | Operate on the global CA (`~/.olef/net/ca.*`) Conflicts with: `project`. |
| `--json` | Accepted for compatibility; output is always JSON. |

#### olef net ca reset

Discard the current CA (backed up to `.bak`) and generate a fresh Olef CA — the way back after an import, and how a per-project CA is first minted (`--project`)

```bash
olef net ca reset --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--project` | Operate on the per-project CA (`<project>/.olef/ca.*`) Conflicts with: `global`. |
| `--global` | Operate on the global CA (`~/.olef/net/ca.*`) Conflicts with: `project`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net start

Start the MITM proxy: spawn the daemon, `adb reverse`, set `http_proxy`

```bash
olef net start --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--port <PORT>` | Proxy listen port (wired to the device via `adb reverse`) Default: `8080`. |
| `--host <HOST>` | Limit capture/MITM to domains or leading '*.' patterns (repeatable). Both example.com and '*.example.com' include the apex and subdomains; a bare fragment matches substrings. Other wildcards are rejected. Omit --host and proxy.hosts to capture all hosts |
| `--foreground` | Run the proxy in the foreground instead of detaching a daemon |
| `--anticache` | Strip cache-validation request headers (force fresh responses) |
| `--anticomp` | Strip Accept-Encoding (force uncompressed responses) |
| `--insecure-upstream` | Accept upstream TLS certificates that fail validation (self-signed, expired, wrong host). Upstream certificates are verified by default, so a tampered network cannot hide behind the Olef CA; use this only for a self-signed dev/staging backend you trust Conflicts with: `verify_upstream`. |
| `--verify-upstream` | Deprecated no-op: upstream TLS is verified by default |
| `--block-host <HOST\|CIDR>` | Refuse connections to this destination (repeatable): a host ('example.com', '*.corp.example', or a bare substring), an IP address, or a CIDR range ('10.0.0.0/8', 'fd00::/8'). Names are resolved when ranges are listed; any blocked address refuses them. Refusals return 403 and appear as `blocked` events |
| `--block-local` | Refuse the host's loopback, link-local and private (RFC 1918, IPv6 ULA) ranges and `localhost` names. Off by default so dev servers on localhost keep working; adb and the proxy's own ports are always refused |
| `--passthrough-host <HOST>` | Relay this host's TLS without interception (repeatable; same forms as --host), for apps that pin certificates. Its connections appear as connection-level flows (`passthrough: true`, byte counts, no bodies). Change the list later with `net passthrough` |
| `--json` | Accepted for compatibility; output is always JSON. |

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

```bash
olef net start --host api.example.com
olef net start --block-local
olef net start --block-host 10.0.0.0/8 --block-host '*.corp.example'
olef net start --passthrough-host pinned.example.com
```

### olef net stop

Stop the proxy and tear down device wiring

```bash
olef net stop --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--revoke-ca` | Also remove the Olef CA from the device trust store |
| `--canary-host <CANARY_HOST>` | Neutral hostname used to verify DNS after teardown Default: `example.com`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net status

Proxy + device-wiring status (daemon, http_proxy, and adb reverse)

```bash
olef net status --help
```

Output: **json**.

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

### olef net log

Recall past flows from the session log

```bash
olef net log --help
```

Output: **jsonl**.

| Argument | Description |
| --- | --- |
| `<action>` | Clear queryable capture history while preserving a running proxy and its rules Values: `clear`. Conflicts with: `after_checkpoint`, `after_id`, `host`, `limit`, `method`, `path`, `rule_id`, `session`, `since`, `status`. |
| `--host <HOST>` | Filter by host (substring), e.g. api.example.com |
| `--path <PATH>` | Filter by URL path (substring) |
| `--method <METHOD>` | Filter by HTTP method (GET, POST, …) |
| `--status <STATUS>` | Filter by response status code |
| `--limit <LIMIT>` / `-n` | Return at most this many flows: the most recent ones, listed oldest first Default: `50`. |
| `--session <SESSION>` | Restrict results to one capture session id returned by `net start` |
| `--since <DURATION>` | Restrict results to a recent duration, e.g. 500ms, 2m, 1h |
| `--after-id <FLOW_ID>` | Exclude this flow id and every older flow in its capture session Conflicts with: `after_checkpoint`. |
| `--after-checkpoint <CHECKPOINT>` | Exclude events at or before a durable capture checkpoint Conflicts with: `after_id`. |
| `--rule-id <RULE_ID>` | Restrict results to flows modified by this rule id |
| `--protocol <PROTOCOL>` | Which protocols to show. Default: HTTP + WebSocket lifecycle (no per-message frames). `websocket` shows WS messages too; `http` hides WebSockets; `all` shows everything Values: `http`, `websocket`, `all`. Conflicts with: `action`. |

### olef net checkpoint

Mark the current capture boundary without stopping the proxy

```bash
olef net checkpoint --help
```

Output: **json**.

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

### olef net show

Full headers + bodies for one flow (or one WebSocket session/message)

```bash
olef net show --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<id>` | **Required.** |
| `--body` | Include request/response bodies (not just headers) |
| `--body-file <PATH>` | Write the full response body to this file (avoids inline-JSON truncation for large responses) instead of printing the flow |
| `--har` | Emit the flow as a single-entry HAR object Conflicts with: `body_file`. |
| `--format <FORMAT>` | Render a WebSocket message payload decoded: `hex`, `json` (pretty), or `protobuf` (schemaless field dump) Values: `hex`, `json`, `protobuf`. |
| `--frames` | Show the per-frame breakdown of a fragmented WebSocket message |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net export

Export flows for interop: `har`, `curl`, or `fixtures` (a versioned, content-addressed replay bundle with exact request keys). Fixture export skips redacted, truncated, streamed, errored, or body-incomplete flows and lists them in `skipped`; naming one flow id rejects it instead

```bash
olef net export --help
```

Output: **json_action_with_artifact**.

| Argument | Description |
| --- | --- |
| `<format>` | **Required.** Export format: har, curl, fixtures, or jsonl (durable line-per-record stream; the machine-readable format for WebSocket messages) Values: `har`, `curl`, `fixtures`, `jsonl`. |
| `<id>` |  |
| `--out <OUT>` / `-o` | Output path: directory for `fixtures`, file for `jsonl` (stdout if omitted for `jsonl`) |
| `--protocol <PROTOCOL>` | jsonl only (refused for other formats): which protocol to export (http \| websocket \| all). Default: all Values: `http`, `websocket`, `all`. |
| `--session <SESSION>` | jsonl only (refused for other formats): restrict to one capture session id |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net ws

Inspect captured WebSocket traffic: sessions, then messages. Cheapest first — bare `net ws` lists sessions; `net ws <id>` lists that session's messages; `net show <message-id>` reveals a full payload

```bash
olef net ws --help
```

Output: **jsonl**.

| Argument | Description |
| --- | --- |
| `<id>` | A session id (e.g. `w1`) to list its messages; omit to list sessions |
| `--host <HOST>` | Filter by host (substring) |
| `--dir <DIR>` | Only one direction: `c2s` (app→server) or `s2c` (server→app) Values: `c2s`, `s2c`. |
| `--opcode <OPCODE>` | Only this frame type Values: `text`, `binary`, `ping`, `pong`, `close`. |
| `--grep <GREP>` | Only messages whose text/preview contains this (substring) |
| `--session <SESSION>` | Restrict to one capture session id from `net start` |
| `--since <DURATION>` | Restrict to a recent duration, e.g. 500ms, 2m, 1h |
| `--stats` | Summarize a session (opcode histogram, per-direction bytes, compression ratio, rate) instead of listing messages; needs a session id |
| `--limit <LIMIT>` / `-n` | Return at most this many rows: the most recent ones, listed oldest first Default: `50`. |

### olef net inject

Inject a WebSocket frame into a live captured session (see `net ws`). Uncompressed and safe even under permessage-deflate. Pick exactly one of --text/--binary/--ping/--pong/--close

```bash
olef net inject --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<session>` | **Required.** Session id from `net ws` (e.g. `w1`) |
| `--dir <DIR>` | **Required.** Direction: `s2c` (to the app, simulate a server push) or `c2s` (to the server, as if from the app) Values: `c2s`, `s2c`. |
| `--text <TEXT>` | Send a text frame with this payload Conflicts with: `binary`, `close`, `ping`, `pong`. |
| `--binary <BINARY>` | Send a binary frame (base64-encoded payload) Conflicts with: `close`, `ping`, `pong`, `text`. |
| `--ping` | Send a ping frame Conflicts with: `binary`, `close`, `pong`, `text`. |
| `--pong` | Send a pong frame Conflicts with: `binary`, `close`, `ping`, `text`. |
| `--close` | Send a close frame Conflicts with: `binary`, `ping`, `pong`, `text`. |
| `--code <CODE>` | Close code (with --close), e.g. 1000 |
| `--reason <REASON>` | Close reason (with --close) |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net intercept

Pause matching flows (or WebSocket frames, with --dir) for agent-in-the-loop editing

```bash
olef net intercept --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--host <HOST>` | Only intercept flows/frames whose host contains this (substring) |
| `--path <PATH>` | Only intercept flows whose URL path contains this (substring) Conflicts with: `dir`. |
| `--method <METHOD>` | Only intercept flows with this HTTP method Conflicts with: `dir`. |
| `--status <STATUS>` | Only intercept flows with this response status (response phase; refused with `--at request`, where no status exists yet) Conflicts with: `dir`. |
| `--dir <DIR>` | Intercept WebSocket frames in this direction instead of HTTP flows: `s2c` (from the server) or `c2s` (from the app) Values: `c2s`, `s2c`. |
| `--opcode <OPCODE>` | With --dir: only intercept frames of this opcode Values: `text`, `binary`, `ping`, `pong`, `close`. |
| `--clear` | Disarm HTTP interception, or WebSocket interception with --dir. Already-held flows/frames keep their existing release/deadline lifecycle |
| `--at <AT>` | Hold at the request phase, response phase, or both (HTTP only) Default: `response`. Values: `request`, `response`, `both`. |
| `--hold-ms <HOLD_MS>` | Auto-act after this long if the agent doesn't (apps time out their own client) Default: `30000`. |
| `--on-timeout <ON_TIMEOUT>` | What to do when the hold deadline passes (fail-open by default) Default: `resume`. Values: `resume`, `drop`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net resume

Release a held flow (optionally mutated) or a held WebSocket frame

```bash
olef net resume --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<id>` | **Required.** |
| `--text <TEXT>` | Held WebSocket frame: replace its payload with this text before forwarding Conflicts with: `binary`, `body`, `set_header`, `set_status`. |
| `--binary <BINARY>` | Held WebSocket frame: replace its payload with this base64 binary Conflicts with: `body`, `set_header`, `set_status`, `text`. |
| `--set-status <SET_STATUS>` | Override the response status code |
| `--set-header <NAME=VALUE>` | Set (or replace) a header; repeatable |
| `--remove-header <NAME>` | Remove a header; repeatable |
| `--body <BODY>` | Replace the body with this literal string Conflicts with: `body_file`. |
| `--body-file <BODY_FILE>` | Replace the body with the contents of this file Conflicts with: `body`. |
| `--replace <REGEX REPL>` | Regex-replace within the body: --replace &lt;REGEX&gt; &lt;REPL&gt; |
| `--delay-ms <DELAY_MS>` | Delay the release by this many milliseconds (simulate latency) |
| `--set-url <SET_URL>` | Rewrite the request URL before forwarding (request phase). The captured flow then describes the forwarded URL and keeps the app's URL in `original_url` |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net drop

Drop a held flow (HTTP 502 by default), or abort its transport explicitly

```bash
olef net drop --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<id>` | **Required.** |
| `--set-status <SET_STATUS>` | Return this HTTP status instead of the default 502 |
| `--transport` | Abort the HTTP connection/stream without sending a response status or body Conflicts with: `set_status`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net respond

Short-circuit a held request with a canned response (never hits the server)

```bash
olef net respond --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<id>` | **Required.** |
| `--set-status <SET_STATUS>` | Status code of the canned response Default: `200`. |
| `--body <BODY>` | Response body as a literal string Conflicts with: `body_file`. |
| `--body-file <BODY_FILE>` | Response body from this file Conflicts with: `body`. |
| `--set-header <NAME=VALUE>` | Set a response header; repeatable |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net passthrough

Relay certificate-pinned hosts' TLS without interception (runtime list)

```bash
olef net passthrough --help
```

Output: **json**.

#### olef net passthrough add

Relay new CONNECT tunnels to these hosts still encrypted: no MITM, no rules, intercepts, or bodies; each connection is recorded as a connection-level flow. Connections already open stay as they are

```bash
olef net passthrough add --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--host <HOST>` | **Required.** Host to pass through: example.com or '*.example.com' (domain and subdomains) or a bare substring (repeatable) |
| `--json` | Accepted for compatibility; output is always JSON. |

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

```bash
olef net passthrough add --host pinned.example.com
olef net passthrough add --host '*.bank.example' --host api.payments.example
```

#### olef net passthrough remove

Intercept these hosts again (exact patterns as listed; repeatable)

```bash
olef net passthrough remove --help
```

Output: **json**.

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

#### olef net passthrough list

List the hosts currently passed through

```bash
olef net passthrough list --help
```

Output: **json**.

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

### olef net rule

Declarative response/request rules

```bash
olef net rule --help
```

Output: **json**.

#### olef net rule add

Add a rule. Request-phase kinds: block, delay, map-local, map-remote, respond, set-request-header. Response-phase kinds: set-status, set-response-header, replace

```bash
olef net rule add --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<kind>` | **Required.** block \| delay \| map-local \| map-remote \| respond \| set-request-header \| set-status \| set-response-header \| replace \| set-json \| ws-drop \| ws-set-text |
| `--host <HOST>` | Match flows whose host contains this (substring) |
| `--path <PATH>` | Match flows whose URL path contains this (substring) |
| `--method <METHOD>` | Match flows with this HTTP method |
| `--dir <DIR>` | `ws-*` rules: restrict to a direction, `c2s` or `s2c` Values: `c2s`, `s2c`. |
| `--opcode <OPCODE>` | `ws-*` rules: restrict to a frame opcode Values: `text`, `binary`, `ping`, `pong`, `close`. |
| `--content-type <CONTENT_TYPE>` | Match flows with this response content-type (substring) |
| `--operation-name <NAME>` | Match a GraphQL operationName in the URL query or JSON request body (HTTP rules) |
| `--status <CODE>` | Synthetic response status (respond only; default 200) |
| `--header <NAME=VALUE>` | Synthetic response header as NAME=VALUE; repeatable (respond only) |
| `--body <BODY>` | Synthetic response body literal (respond only) Conflicts with: `body_file`. |
| `--body-file <PATH>` | Read the synthetic response body from a file (respond only) Conflicts with: `body`. |
| `<args>` | Kind-specific positionals: block [status], delay &lt;ms&gt;, map-local &lt;file&gt;, map-remote &lt;host:port&gt;, respond (use flags), set-request-header &lt;name&gt; &lt;value&gt;, set-response-header &lt;name&gt; &lt;value&gt;, set-status &lt;code&gt;, replace &lt;regex&gt; &lt;repl&gt;, set-json &lt;pointer&gt; &lt;expected-json&gt; &lt;value-json&gt; [max-applications=1] |
| `--json` | Accepted for compatibility; output is always JSON. |

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

```bash
olef net rule add map-local response.json --host api.example.com --path /v1/dict
olef net rule add set-status 503 --host api.example.com
olef net rule add respond --host api.example.com --method POST --operation-name currentSession --status 401 --header content-type=application/json --body '{"errors":[{"message":"Unauthorized"}]}'
olef net rule add set-request-header x-debug 1 --host api.example.com
olef net rule add set-response-header cache-control no-store --host api.example.com
```

#### olef net rule list

List active rules

```bash
olef net rule list --help
```

Output: **json**.

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

#### olef net rule rm

Remove a rule by id

```bash
olef net rule rm --help
```

Output: **json**.

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

#### olef net rule clear

Remove all rules

```bash
olef net rule clear --help
```

Output: **json**.

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

#### olef net rule lint

Validate a rules file without requiring a device or running proxy

```bash
olef net rule lint --help
```

Output: **json**.

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

#### olef net rule explain

Explain which rules match one concrete flow and why

```bash
olef net rule explain --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `<file>` | **Required.** JSON array or legacy JSONL rules file |
| `--host <HOST>` | **Required.** Observed request/WebSocket host |
| `--path <PATH>` | Observed request path and query Default: `/`. |
| `--method <METHOD>` | Observed HTTP method Default: `GET`. |
| `--status <STATUS>` | Response status; selects response-phase explanation Conflicts with: `dir`, `opcode`. |
| `--content-type <CONTENT_TYPE>` | Response content type; selects response-phase explanation Conflicts with: `dir`, `opcode`. |
| `--body <BODY>` | Request body used by GraphQL operation matchers Default: ``. |
| `--dir <DIR>` | WebSocket direction; selects WebSocket-phase explanation Values: `c2s`, `s2c`. |
| `--opcode <OPCODE>` | WebSocket opcode; selects WebSocket-phase explanation Values: `text`, `binary`, `ping`, `pong`, `close`. |
| `--json` | Accepted for compatibility; output is always JSON. |

### olef net override

Convenience: map URL-matching requests to a local response file

```bash
olef net override --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--url <GLOB>` | **Required.** URL glob to match, e.g. https://api.example.com/v1/dict* |
| `--file <PATH>` | **Required.** Local file to serve as the response body |
| `--json` | Accepted for compatibility; output is always JSON. |

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

```bash
olef net override --url 'https://api.example.com/v1/dict*' --file response.json
```

### olef net rules

Atomically replace active rules from a validated JSON array/JSONL file

```bash
olef net rules --help
```

Output: **json**.

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

### olef net replay

Atomically serve a validated fixtures bundle without a backend

```bash
olef net replay --help
```

Output: **json**.

| Argument | Description |
| --- | --- |
| `--from <FROM>` | Directory (or manifest.json) produced by `net export fixtures`. Historical raw FlowRecord JSONL remains supported with strict parsing |
| `--host <HOST>` | Select this exact canonical host from a multi-host bundle Conflicts with: `clear`. |
| `--clear` | Stop serving the active replay set; requests reach their servers again Conflicts with: `from`. |
| `--json` | Accepted for compatibility; output is always JSON. |