> ## Documentation Index
> Fetch the complete documentation index at: https://ctpf.q-uestionable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy CLI Commands

> Command reference for starting, replaying, exporting, and inspecting MCP sessions

## ctpf proxy

Intercept and replay MCP traffic for inspection, testing, and analysis.

```bash theme={null}
ctpf proxy [COMMAND] [OPTIONS]
```

## Commands

### proxy start

Start the proxy with an interactive TUI.

```bash theme={null}
ctpf proxy start --transport TRANSPORT [OPTIONS]
```

**Options:**

| Option             | Required                                     | Type   | Description                                          |
| ------------------ | -------------------------------------------- | ------ | ---------------------------------------------------- |
| `--transport`      | Yes                                          | string | Transport type: `stdio`, `sse`, or `streamable-http` |
| `--target-command` | When transport is `stdio`                    | string | Server command to proxy (stdio only)                 |
| `--target-url`     | When transport is `sse` or `streamable-http` | string | Server URL to proxy (HTTP transports only)           |
| `--intercept`      | No                                           | flag   | Start in intercept mode (default: passthrough)       |
| `--session-file`   | No                                           | string | Auto-save session to this file on exit               |

**Examples:**

<CodeGroup>
  ```bash stdio theme={null}
  ctpf proxy start \
    --transport stdio \
    --target-command "python my_server.py" \
    --intercept
  ```

  ```bash HTTP theme={null}
  ctpf proxy start \
    --transport sse \
    --target-url "http://localhost:3000" \
    --session-file session.json
  ```
</CodeGroup>

<Tip>
  Use passthrough mode (default) for passive capture of complete interactions. Use intercept mode when you need to halt and inspect or modify specific messages.
</Tip>

### proxy replay

Replay captured messages against a live server.

```bash theme={null}
ctpf proxy replay --session-file FILE [OPTIONS]
```

**Options:**

| Option             | Required | Type   | Description                                             |
| ------------------ | -------- | ------ | ------------------------------------------------------- |
| `--session-file`   | Yes      | string | Path to saved session file                              |
| `--target-command` | Yes\*    | string | Server command for replay (stdio)                       |
| `--target-url`     | Yes\*    | string | Server URL for replay (SSE/HTTP)                        |
| `--output`         | No       | string | Save replay results to JSON file                        |
| `--timeout`        | No       | float  | Per-message response timeout in seconds (default: 10.0) |
| `--no-handshake`   | No       | flag   | Skip auto-handshake; session must start with initialize |

\* Either `--target-command` or `--target-url` is required.

**Examples:**

<CodeGroup>
  ```bash stdio theme={null}
  ctpf proxy replay \
    --session-file session.json \
    --target-command "python my_server.py" \
    --output results.json
  ```

  ```bash HTTP with timeout theme={null}
  ctpf proxy replay \
    --session-file session.json \
    --target-url "http://localhost:3000" \
    --timeout 30.0 \
    --output results.json
  ```
</CodeGroup>

<Note>
  By default, the replay engine sends a synthetic `initialize` handshake before replaying messages. Use `--no-handshake` if your session already includes the full handshake sequence.
</Note>

### proxy export

Export a session to JSON.

```bash theme={null}
ctpf proxy export --session-file FILE --output OUTPUT [OPTIONS]
```

**Options:**

| Option            | Required | Type   | Description                     |
| ----------------- | -------- | ------ | ------------------------------- |
| `--session-file`  | Yes      | string | Path to saved session file      |
| `--output`        | Yes      | string | Output file path                |
| `--output-format` | No       | string | Export format (default: `json`) |

**Example:**

```bash theme={null}
ctpf proxy export \
  --session-file session.json \
  --output report.json
```

### proxy inspect

Print session contents to stdout for review.

```bash theme={null}
ctpf proxy inspect --session-file FILE [OPTIONS]
```

**Options:**

| Option            | Required | Type   | Description                              |
| ----------------- | -------- | ------ | ---------------------------------------- |
| `--session-file`  | Yes      | string | Path to saved session file               |
| `--verbose`, `-v` | No       | flag   | Show full JSON payloads for each message |

**Example:**

```bash theme={null}
ctpf proxy inspect --session-file session.json -v
```

**Output format:**

```
Session: abc-123
Transport: stdio
Server command: python my_server.py
Messages: 12

  #000 → initialize id=1
  #001 ← (response) id=1
  #002 → notifications/initialized
  #003 → tools/call id=2
```

Add `-v` to include full JSON payloads.

## Message Direction

In `inspect` output:

* `→` denotes client-to-server messages (requests and notifications sent to the server)
* `←` denotes server-to-client messages (responses and notifications from the server)

In the TUI (`proxy start`):

* `▶` denotes client-to-server messages
* `◀` denotes server-to-client messages
* `⏸` prefix on held messages (intercept mode)
* `✕` prefix on dropped messages

## Exit Codes

| Code | Meaning                                                             |
| ---- | ------------------------------------------------------------------- |
| 0    | Success                                                             |
| 1    | Command error (invalid options, file not found, validation failure) |
| 130  | Interrupted by user (Ctrl+C)                                        |