procsi 0.2.7 → 0.4.0

package/README.md

@@ -4,35 +4,31 @@
 [![CI](https://github.com/mtford90/procsi/actions/workflows/ci.yml/badge.svg)](https://github.com/mtford90/procsi/actions/workflows/ci.yml)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
-HTTP interception for the terminal. Each project gets its own proxy, its own traffic database, its own mocks — all in a `.procsi/` directory that lives alongside your code.
+Procsi is a terminal-based, project-isolated HTTP proxy with a powerful CLI & MCP server. Quickly intercept, inspect & rewrite HTTP traffic from the comfort of your terminal or favourite AI agent.
 
 ![procsi demo](demo.gif)
 
-No browser extensions, no global system proxy, no separate apps. A MITM proxy captures your traffic, a lazygit-style TUI lets you browse it, TypeScript files let you mock it, and AI agents can query and manipulate all of it via MCP.
+## Feature Highlights
+
+- **Project isolation** — each project gets its own `.procsi/` directory with a separate daemon, database, CA cert and interceptors
+- **MCP server** — AI agents get full access to your captured traffic and can write interceptor files for you. Search, filter, inspect, mock — all via tool calls.
+- **Interceptors** — mock, modify or observe traffic with `.ts` files. Match on anything, query past traffic from within handlers, compose complex scenarios.
 
 ## Quick Start
 
 ```bash
 npm install -g procsi
 
-# In your project directory
+# Configure environment e.g. HTTP_PROXY
 eval "$(procsi on)"
+
+# Send a request
 curl https://api.example.com/users
+
+# Open UI
 procsi tui
 ```
 
-Requires Node.js 20+.
-
-## Features
-
-- **Project-scoped** — each project gets its own `.procsi/` directory with a separate daemon, database, CA cert and interceptors. No cross-project bleed.
-- **TypeScript interceptors** — mock, modify or observe traffic with `.ts` files. Match on anything, query past traffic from within handlers, compose complex scenarios.
-- **MCP server** — AI agents get full access to your captured traffic and can write interceptor files for you. Search, filter, inspect, mock — all via tool calls.
-- **Terminal TUI** — vim-style keybindings, mouse support, JSON explorer, filtering. Stays in your terminal where you're already working.
-- **HTTPS** — automatic CA certificate generation and trust
-- **Export** — copy as curl, export as HAR, save bodies to disk
-- **Zero config** — works with curl, wget, Node.js, Python, Go, Rust and anything else that respects `HTTP_PROXY`
-
 ## Project Isolation
 
 procsi doesn't use a global system proxy. Each project gets its own `.procsi/` directory in the project root (detected by `.git` or an existing `.procsi/`):
@@ -50,7 +46,121 @@ your-project/
 └── src/...
 ```
 
-Separate daemon, separate database, separate certificates. You can run procsi in multiple projects at the same time without them interfering with each other.
+Separate daemon, database, certificates etc. You can run procsi in multiple projects at the same time without them interfering with each other.
+
+## Use cases
+
+- AI analysis
+- Chaos monkey
+- Mock out APIs that do not yet exist
+
+## MCP Integration
+
+procsi has a built-in [MCP](https://modelcontextprotocol.io/) server that gives AI agents full access to your captured traffic and interceptor system. Agents can search through requests, inspect headers and bodies, and write interceptor files directly into `.procsi/interceptors/`.
+
+This means you can ask things like:
+
+- "Find all failing requests to the payments API and write mocks that return valid responses"
+- "Make every 5th request to /api/users return a 429 so I can test rate limiting"
+- "What's the average response time for requests to the auth service in the last hour?"
+- "Write an interceptor that logs all requests with missing auth headers"
+- "Send me a notification whenever an api request fails"
+
+The agent reads your traffic, writes the TypeScript, and procsi hot-reloads it.
+
+### Setup
+
+Add procsi to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "procsi": {
+      "command": "procsi",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+The proxy must be running (`eval "$(procsi on)"`) — the MCP server connects to the same daemon as the TUI.
+
+### Agent Skill
+
+procsi also ships an agent skill that teaches AI assistants how to use the MCP tools properly. Gets you better results out of the box.
+
+**Claude Code:**
+
+```bash
+/plugin marketplace add mtford90/procsi
+/plugin install procsi
+```
+
+**npm-agentskills** (works with Cursor, Copilot, Codex, etc.):
+
+```bash
+npx agents export --target claude
+```
+
+### Available Tools
+
+| Tool                         | Description                                          |
+| ---------------------------- | ---------------------------------------------------- |
+| `procsi_get_status`          | Daemon status, proxy port, request count             |
+| `procsi_list_requests`       | Search and filter captured requests                  |
+| `procsi_get_request`         | Full request details by ID (headers, bodies, timing) |
+| `procsi_search_bodies`       | Full-text search through body content                |
+| `procsi_query_json`          | Extract values from JSON bodies via JSONPath         |
+| `procsi_count_requests`      | Count matching requests                              |
+| `procsi_clear_requests`      | Delete all captured requests                         |
+| `procsi_list_sessions`       | List active proxy sessions                           |
+| `procsi_list_interceptors`   | List loaded interceptors with status and errors      |
+| `procsi_reload_interceptors` | Reload interceptors from disk                        |
+
+### Filtering
+
+Most tools accept these filters:
+
+| Parameter          | Description                                 | Example                               |
+| ------------------ | ------------------------------------------- | ------------------------------------- |
+| `method`           | HTTP method(s), comma-separated             | `"GET,POST"`                          |
+| `status_range`     | Status code, Nxx pattern, or range          | `"4xx"`, `"401"`, `"500-503"`         |
+| `search`           | Substring match on URL/path                 | `"api/users"`                         |
+| `host`             | Exact or suffix match (prefix with `.`)     | `"api.example.com"`, `".example.com"` |
+| `path`             | Path prefix match                           | `"/api/v2"`                           |
+| `since` / `before` | Time window (ISO 8601)                      | `"2024-01-15T10:30:00Z"`              |
+| `header_name`      | Filter by header existence or value         | `"content-type"`                      |
+| `header_value`     | Exact header value (requires `header_name`) | `"application/json"`                  |
+| `header_target`    | Which headers to search                     | `"request"`, `"response"`, `"both"`   |
+| `source`           | Filter by request source                    | `"node"`, `"python"`                  |
+| `intercepted_by`   | Filter by interceptor name                  | `"mock-users"`                        |
+| `offset`           | Pagination offset (0-based)                 | `0`                                   |
+| `limit`            | Max results (default 50, max 500)           | `100`                                 |
+
+`procsi_get_request` accepts comma-separated IDs for batch fetching (e.g. `"id1,id2,id3"`).
+
+`procsi_query_json` also takes:
+
+| Parameter | Description                                                           | Example      |
+| --------- | --------------------------------------------------------------------- | ------------ |
+| `target`  | Which body to query: `"request"`, `"response"`, or `"both"` (default) | `"response"` |
+| `value`   | Exact value match after JSONPath extraction                           | `"active"`   |
+
+### Output Formats
+
+All query tools accept a `format` parameter:
+
+- `text` (default) — markdown summaries, readable by humans and AI
+- `json` — structured JSON for programmatic use
+
+### Examples
+
+```
+procsi_list_requests({ status_range: "5xx", path: "/api" })
+procsi_search_bodies({ query: "error_code", method: "POST" })
+procsi_query_json({ json_path: "$.user.id", target: "response" })
+procsi_list_requests({ header_name: "authorization", header_target: "request" })
+```
 
 ## Interceptors
 
@@ -148,21 +258,21 @@ export default {
 
 ### Handler Context
 
-| Property | Description |
-|----------|-------------|
-| `ctx.request` | The incoming request (frozen, read-only) |
+| Property        | Description                               |
+| --------------- | ----------------------------------------- |
+| `ctx.request`   | The incoming request (frozen, read-only)  |
 | `ctx.forward()` | Forward to upstream, returns the response |
-| `ctx.procsi` | Query captured traffic (see below) |
-| `ctx.log(msg)` | Write to `.procsi/procsi.log` |
+| `ctx.procsi`    | Query captured traffic (see below)        |
+| `ctx.log(msg)`  | Write to `.procsi/procsi.log`             |
 
 #### `ctx.procsi`
 
-| Method | Description |
-|--------|-------------|
-| `countRequests(filter?)` | Count matching requests |
-| `listRequests({ filter?, limit?, offset? })` | List request summaries |
-| `getRequest(id)` | Full request details by ID |
-| `searchBodies({ query, ...filter? })` | Full-text search through bodies |
+| Method                                       | Description                                  |
+| -------------------------------------------- | -------------------------------------------- |
+| `countRequests(filter?)`                     | Count matching requests                      |
+| `listRequests({ filter?, limit?, offset? })` | List request summaries                       |
+| `getRequest(id)`                             | Full request details by ID                   |
+| `searchBodies({ query, ...filter? })`        | Full-text search through bodies              |
 | `queryJsonBodies({ json_path, ...filter? })` | Extract values from JSON bodies via JSONPath |
 
 ### How Interceptors Work
@@ -176,112 +286,6 @@ export default {
 - `ctx.log()` writes to `.procsi/procsi.log` since `console.log` goes nowhere in the daemon
 - Use `satisfies Interceptor` for full intellisense
 
-## MCP Integration
-
-procsi has a built-in [MCP](https://modelcontextprotocol.io/) server that gives AI agents full access to your captured traffic and interceptor system. Agents can search through requests, inspect headers and bodies, and write interceptor files directly into `.procsi/interceptors/`.
-
-This means you can ask things like:
-
-- "Find all failing requests to the payments API and write mocks that return valid responses"
-- "Make every 5th request to /api/users return a 429 so I can test rate limiting"
-- "What's the average response time for requests to the auth service in the last hour?"
-- "Write an interceptor that logs all requests with missing auth headers"
-
-The agent reads your traffic, writes the TypeScript, and procsi hot-reloads it.
-
-### Setup
-
-Add procsi to your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "procsi": {
-      "command": "procsi",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-The proxy must be running (`eval "$(procsi on)"`) — the MCP server connects to the same daemon as the TUI.
-
-### Agent Skill
-
-procsi also ships an agent skill that teaches AI assistants how to use the MCP tools properly. Gets you better results out of the box.
-
-**Claude Code:**
-
-```bash
-/plugin marketplace add mtford90/procsi
-/plugin install procsi
-```
-
-**npm-agentskills** (works with Cursor, Copilot, Codex, etc.):
-
-```bash
-npx agents export --target claude
-```
-
-### Available Tools
-
-| Tool | Description |
-|------|-------------|
-| `procsi_get_status` | Daemon status, proxy port, request count |
-| `procsi_list_requests` | Search and filter captured requests |
-| `procsi_get_request` | Full request details by ID (headers, bodies, timing) |
-| `procsi_search_bodies` | Full-text search through body content |
-| `procsi_query_json` | Extract values from JSON bodies via JSONPath |
-| `procsi_count_requests` | Count matching requests |
-| `procsi_clear_requests` | Delete all captured requests |
-| `procsi_list_sessions` | List active proxy sessions |
-| `procsi_list_interceptors` | List loaded interceptors with status and errors |
-| `procsi_reload_interceptors` | Reload interceptors from disk |
-
-### Filtering
-
-Most tools accept these filters:
-
-| Parameter | Description | Example |
-|-----------|-------------|---------|
-| `method` | HTTP method(s), comma-separated | `"GET,POST"` |
-| `status_range` | Status code, Nxx pattern, or range | `"4xx"`, `"401"`, `"500-503"` |
-| `search` | Substring match on URL/path | `"api/users"` |
-| `host` | Exact or suffix match (prefix with `.`) | `"api.example.com"`, `".example.com"` |
-| `path` | Path prefix match | `"/api/v2"` |
-| `since` / `before` | Time window (ISO 8601) | `"2024-01-15T10:30:00Z"` |
-| `header_name` | Filter by header existence or value | `"content-type"` |
-| `header_value` | Exact header value (requires `header_name`) | `"application/json"` |
-| `header_target` | Which headers to search | `"request"`, `"response"`, `"both"` |
-| `intercepted_by` | Filter by interceptor name | `"mock-users"` |
-| `offset` | Pagination offset (0-based) | `0` |
-| `limit` | Max results (default 50, max 500) | `100` |
-
-`procsi_get_request` accepts comma-separated IDs for batch fetching (e.g. `"id1,id2,id3"`).
-
-`procsi_query_json` also takes:
-
-| Parameter | Description | Example |
-|-----------|-------------|---------|
-| `target` | Which body to query: `"request"`, `"response"`, or `"both"` (default) | `"response"` |
-| `value` | Exact value match after JSONPath extraction | `"active"` |
-
-### Output Formats
-
-All query tools accept a `format` parameter:
-
-- `text` (default) — markdown summaries, readable by humans and AI
-- `json` — structured JSON for programmatic use
-
-### Examples
-
-```
-procsi_list_requests({ status_range: "5xx", path: "/api" })
-procsi_search_bodies({ query: "error_code", method: "POST" })
-procsi_query_json({ json_path: "$.user.id", target: "response" })
-procsi_list_requests({ header_name: "authorization", header_target: "request" })
-```
-
 ## How It Works
 
 ```
@@ -323,15 +327,15 @@ procsi_list_requests({ header_name: "authorization", header_target: "request" })
 
 `eval "$(procsi on)"` sets these in your shell (`eval "$(procsi off)"` unsets them):
 
-| Variable | Purpose |
-|----------|---------|
-| `HTTP_PROXY` | Proxy URL for HTTP clients |
-| `HTTPS_PROXY` | Proxy URL for HTTPS clients |
-| `SSL_CERT_FILE` | CA cert path (curl, git, etc.) |
-| `REQUESTS_CA_BUNDLE` | CA cert path (Python requests) |
-| `NODE_EXTRA_CA_CERTS` | CA cert path (Node.js) |
-| `PROCSI_SESSION_ID` | UUID identifying the current session |
-| `PROCSI_LABEL` | Session label (when `-l` flag used) |
+| Variable              | Purpose                              |
+| --------------------- | ------------------------------------ |
+| `HTTP_PROXY`          | Proxy URL for HTTP clients           |
+| `HTTPS_PROXY`         | Proxy URL for HTTPS clients          |
+| `SSL_CERT_FILE`       | CA cert path (curl, git, etc.)       |
+| `REQUESTS_CA_BUNDLE`  | CA cert path (Python requests)       |
+| `NODE_EXTRA_CA_CERTS` | CA cert path (Node.js)               |
+| `PROCSI_SESSION_ID`   | UUID identifying the current session |
+| `PROCSI_LABEL`        | Session label (when `-l` flag used)  |
 
 ## Configuration
 
@@ -346,12 +350,12 @@ Create `.procsi/config.json` to override defaults. All fields are optional:
 }
 ```
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `maxStoredRequests` | `5000` | Max requests in the database. Oldest evicted automatically. |
-| `maxBodySize` | `10485760` (10 MB) | Max body size to capture. Larger bodies are proxied but not stored. |
-| `maxLogSize` | `10485760` (10 MB) | Max log file size before rotation. |
-| `pollInterval` | `2000` | TUI polling interval in ms. Lower = faster updates, more IPC traffic. |
+| Setting             | Default            | Description                                                           |
+| ------------------- | ------------------ | --------------------------------------------------------------------- |
+| `maxStoredRequests` | `5000`             | Max requests in the database. Oldest evicted automatically.           |
+| `maxBodySize`       | `10485760` (10 MB) | Max body size to capture. Larger bodies are proxied but not stored.   |
+| `maxLogSize`        | `10485760` (10 MB) | Max log file size before rotation.                                    |
+| `pollInterval`      | `2000`             | TUI polling interval in ms. Lower = faster updates, more IPC traffic. |
 
 Missing or invalid values fall back to defaults.
 
@@ -359,14 +363,14 @@ Missing or invalid values fall back to defaults.
 
 Anything that respects `HTTP_PROXY` works:
 
-| Client | Support |
-|--------|---------|
-| curl | Automatic |
-| wget | Automatic |
+| Client                       | Support                    |
+| ---------------------------- | -------------------------- |
+| curl                         | Automatic                  |
+| wget                         | Automatic                  |
 | Node.js (fetch, axios, etc.) | With `NODE_EXTRA_CA_CERTS` |
-| Python (requests, httpx) | With `REQUESTS_CA_BUNDLE` |
-| Go | Automatic |
-| Rust (reqwest) | Automatic |
+| Python (requests, httpx)     | With `REQUESTS_CA_BUNDLE`  |
+| Go                           | Automatic                  |
+| Rust (reqwest)               | Automatic                  |
 
 ## Export
 
@@ -394,59 +398,59 @@ Mouse support: click to select, scroll to navigate, click panels to focus.
 
 ### Main View
 
-| Key | Action |
-|-----|--------|
-| `j`/`k` or `↑`/`↓` | Navigate up/down |
-| `g` / `G` | Jump to first / last item |
-| `Ctrl+u` / `Ctrl+d` | Half-page up / down |
-| `Ctrl+f` / `Ctrl+b` | Full-page down / up |
-| `Tab` / `Shift+Tab` | Next / previous panel |
-| `1`-`5` | Jump to section (list / request / request body / response / response body) |
-| `Enter` | Open body in full-screen viewer |
-| `/` | Open filter bar |
-| `u` | Toggle full URL display |
-| `c` | Copy request as curl |
-| `y` | Copy body to clipboard |
-| `s` | Export body (opens export modal) |
-| `H` | Export all as HAR |
-| `r` | Refresh |
-| `?` | Help |
-| `i` | Proxy connection info |
-| `q` | Quit |
+| Key                 | Action                                                                     |
+| ------------------- | -------------------------------------------------------------------------- |
+| `j`/`k` or `↑`/`↓`  | Navigate up/down                                                           |
+| `g` / `G`           | Jump to first / last item                                                  |
+| `Ctrl+u` / `Ctrl+d` | Half-page up / down                                                        |
+| `Ctrl+f` / `Ctrl+b` | Full-page down / up                                                        |
+| `Tab` / `Shift+Tab` | Next / previous panel                                                      |
+| `1`-`5`             | Jump to section (list / request / request body / response / response body) |
+| `Enter`             | Open body in full-screen viewer                                            |
+| `/`                 | Open filter bar                                                            |
+| `u`                 | Toggle full URL display                                                    |
+| `c`                 | Copy request as curl                                                       |
+| `y`                 | Copy body to clipboard                                                     |
+| `s`                 | Export body (opens export modal)                                           |
+| `H`                 | Export all as HAR                                                          |
+| `r`                 | Refresh                                                                    |
+| `?`                 | Help                                                                       |
+| `i`                 | Proxy connection info                                                      |
+| `q`                 | Quit                                                                       |
 
 ### Filter Bar (`/`)
 
-| Key | Action |
-|-----|--------|
-| `Tab` / `Shift+Tab` | Cycle between search, method, status fields |
-| `←` / `→` | Cycle method (ALL/GET/POST/PUT/PATCH/DELETE) or status (ALL/2xx-5xx) |
-| `Return` | Apply filter |
-| `Esc` | Cancel and revert |
+| Key                 | Action                                                               |
+| ------------------- | -------------------------------------------------------------------- |
+| `Tab` / `Shift+Tab` | Cycle between search, method, status fields                          |
+| `←` / `→`           | Cycle method (ALL/GET/POST/PUT/PATCH/DELETE) or status (ALL/2xx-5xx) |
+| `Return`            | Apply filter                                                         |
+| `Esc`               | Cancel and revert                                                    |
 
 ### JSON Explorer (Enter on a JSON body)
 
-| Key | Action |
-|-----|--------|
-| `j`/`k` | Navigate nodes |
-| `Enter`/`l` | Expand/collapse node |
-| `h` | Collapse node |
-| `e` / `c` | Expand / collapse all |
-| `/` | Filter by path |
-| `n` / `N` | Next / previous match |
-| `y` | Copy value |
-| `q` / `Esc` | Close |
+| Key         | Action                |
+| ----------- | --------------------- |
+| `j`/`k`     | Navigate nodes        |
+| `Enter`/`l` | Expand/collapse node  |
+| `h`         | Collapse node         |
+| `e` / `c`   | Expand / collapse all |
+| `/`         | Filter by path        |
+| `n` / `N`   | Next / previous match |
+| `y`         | Copy value            |
+| `q` / `Esc` | Close                 |
 
 ### Text Viewer (Enter on a non-JSON body)
 
-| Key | Action |
-|-----|--------|
-| `j`/`k` | Scroll line by line |
-| `Space` | Page down |
-| `g` / `G` | Top / bottom |
-| `/` | Search text |
-| `n` / `N` | Next / previous match |
-| `y` | Copy to clipboard |
-| `q` / `Esc` | Close |
+| Key         | Action                |
+| ----------- | --------------------- |
+| `j`/`k`     | Scroll line by line   |
+| `Space`     | Page down             |
+| `g` / `G`   | Top / bottom          |
+| `/`         | Search text           |
+| `n` / `N`   | Next / previous match |
+| `y`         | Copy to clipboard     |
+| `q` / `Esc` | Close                 |
 
 </details>
 
@@ -454,10 +458,10 @@ Mouse support: click to select, scroll to navigate, click panels to focus.
 
 ### Global Options
 
-| Flag | Description |
-|------|-------------|
-| `-v, --verbose` | Increase log verbosity (stackable: `-vv`, `-vvv`) |
-| `-d, --dir <path>` | Override project root directory |
+| Flag               | Description                                       |
+| ------------------ | ------------------------------------------------- |
+| `-v, --verbose`    | Increase log verbosity (stackable: `-vv`, `-vvv`) |
+| `-d, --dir <path>` | Override project root directory                   |
 
 ### `procsi on`
 
@@ -469,10 +473,11 @@ eval "$(procsi on)"
 
 If run directly in a TTY (without `eval`), shows usage instructions.
 
-| Flag | Description |
-|------|-------------|
-| `-l, --label <label>` | Label this session (visible in TUI and MCP) |
-| `--no-restart` | Don't auto-restart daemon on version mismatch |
+| Flag                  | Description                                   |
+| --------------------- | --------------------------------------------- |
+| `-l, --label <label>`  | Label this session (visible in TUI and MCP)              |
+| `-s, --source <name>` | Label the source process (auto-detected from PID if omitted) |
+| `--no-restart`         | Don't auto-restart daemon on version mismatch            |
 
 ### `procsi off`
 
@@ -486,8 +491,8 @@ eval "$(procsi off)"
 
 Open the interactive TUI.
 
-| Flag | Description |
-|------|-------------|
+| Flag   | Description                                 |
+| ------ | ------------------------------------------- |
 | `--ci` | CI mode: render once and exit (for testing) |
 
 ### `procsi status`
@@ -502,6 +507,95 @@ Stop the daemon.
 
 Restart the daemon (or start it if not running).
 
+### `procsi requests`
+
+List and filter captured requests. Output is a colour-coded table with short IDs — pipe to other tools or use `--json` for structured output.
+
+```bash
+procsi requests                              # list recent (default limit 50)
+procsi requests --method GET,POST            # filter by method
+procsi requests --status 4xx                 # filter by status range
+procsi requests --host api.example.com       # filter by host
+procsi requests --path /api/v2               # filter by path prefix
+procsi requests --search "keyword"           # substring match on URL
+procsi requests --since 5m                   # last 5 minutes
+procsi requests --since yesterday            # since midnight yesterday
+procsi requests --since 10am --before 11am   # time window
+procsi requests --header "content-type:application/json"  # header filter
+procsi requests --intercepted-by mock-users  # interceptor filter
+procsi requests --limit 100 --offset 50      # pagination
+procsi requests --json                       # JSON output
+```
+
+| Flag                       | Description                                              |
+| -------------------------- | -------------------------------------------------------- |
+| `--method <methods>`       | Filter by HTTP method (comma-separated)                  |
+| `--status <range>`         | Status range: `2xx`, `4xx`, exact `401`, etc.            |
+| `--host <host>`            | Filter by hostname                                       |
+| `--path <prefix>`          | Filter by path prefix                                    |
+| `--search <text>`          | Substring match on URL                                   |
+| `--since <time>`           | Since time (5m, 2h, 10am, yesterday, monday, 2024-01-01) |
+| `--before <time>`          | Before time (same formats as --since)                    |
+| `--header <spec>`          | Header name or name:value                                |
+| `--header-target <target>` | `request`, `response`, or `both` (default)               |
+| `--source <name>`          | Filter by request source (e.g. node, python)             |
+| `--intercepted-by <name>`  | Filter by interceptor name                               |
+| `--limit <n>`              | Max results (default 50)                                 |
+| `--offset <n>`             | Skip results (default 0)                                 |
+| `--json`                   | JSON output                                              |
+
+#### `procsi requests search <query>`
+
+Full-text search through request and response bodies.
+
+#### `procsi requests query <jsonpath>`
+
+Query JSON bodies using JSONPath expressions (e.g. `$.data.id`). Supports `--value`, `--target` (request/response/both).
+
+#### `procsi requests count`
+
+Count requests matching the current filters.
+
+#### `procsi requests clear`
+
+Clear all captured requests. Prompts for confirmation unless `--yes` is passed.
+
+### `procsi request <id>`
+
+View a single request in detail. Accepts full UUIDs or abbreviated prefixes (first 7+ characters).
+
+```bash
+procsi request a1b2c3d              # full detail view
+procsi request a1b2c3d --json       # JSON output
+```
+
+#### `procsi request <id> body`
+
+Dump the response body to stdout (raw, pipeable). Use `--request` for the request body instead.
+
+```bash
+procsi request a1b2c3d body                # response body
+procsi request a1b2c3d body --request      # request body
+procsi request a1b2c3d body | jq .         # pipe to jq
+```
+
+#### `procsi request <id> export <format>`
+
+Export a request as `curl` or `har`.
+
+```bash
+procsi request a1b2c3d export curl
+procsi request a1b2c3d export har
+```
+
+### `procsi sessions`
+
+List active proxy sessions.
+
+| Flag     | Description |
+| -------- | ----------- |
+| `--json` | JSON output |
+
 ### `procsi clear`
 
 Clear all captured requests.
@@ -530,6 +624,41 @@ Scaffold an example interceptor in `.procsi/interceptors/`.
 
 Reload interceptors from disk without restarting the daemon.
 
+### `procsi interceptors logs`
+
+View the interceptor event log. Events include match results, mock responses, errors, timeouts, and `ctx.log()` output.
+
+```bash
+procsi interceptors logs                         # recent events
+procsi interceptors logs --name mock-users       # filter by interceptor
+procsi interceptors logs --level error           # filter by level
+procsi interceptors logs --limit 100             # more results
+procsi interceptors logs --follow                # live tail (Ctrl+C to stop)
+procsi interceptors logs --follow --json         # live tail as NDJSON
+```
+
+| Flag                   | Description                         |
+| ---------------------- | ----------------------------------- |
+| `--name <interceptor>` | Filter by interceptor name          |
+| `--level <level>`      | Filter by level (info, warn, error) |
+| `--limit <n>`          | Max events (default 50)             |
+| `--follow`             | Live tail — poll for new events     |
+| `--json`               | JSON output                         |
+
+#### `procsi interceptors logs clear`
+
+Clear the interceptor event log.
+
+### `procsi completions <shell>`
+
+Generate shell completion scripts. Supports `zsh`, `bash`, and `fish`.
+
+```bash
+eval "$(procsi completions zsh)"    # add to .zshrc
+eval "$(procsi completions bash)"   # add to .bashrc
+procsi completions fish | source    # add to fish config
+```
+
 ## Development
 
 ```bash
@@ -564,13 +693,11 @@ procsi daemon stop
 eval "$(procsi on)"
 ```
 
-### Terminal too small
-
-The TUI needs at least 60 columns by 10 rows.
-
 ### Requests not appearing
 
-Your HTTP client needs to respect proxy environment variables. Browsers typically don't — use curl, wget, or language-level HTTP clients instead.
+Your HTTP client needs to respect proxy environment variables.
+
+There are workarounds implemented for node - e.g. fetch override. Other libraries in different environments may need a similar treatment.
 
 ## Licence