httpeep-cli Complete Guide: Command-Line HTTP Proxy Debugging

What is httpeep-cli?

httpeep-cli is the command-line interface for HTTPeep. It gives you full access to the proxy engine—capturing traffic, querying sessions, managing rules, and replaying requests—without opening the desktop app UI.

It's designed for three use cases:

Script and CI integration — start the proxy, run tests, capture sessions, then query them programmatically
AI agent friendliness — structured JSON output makes it easy for tools like Claude Code or Codex to parse and reason about captured traffic
Power user workflows — record/replay, bulk rule management, real-time terminal monitoring

httpeep-cli communicates with the HTTPeep proxy engine via its local MCP service, so the desktop app must be running (or you can start the proxy via the CLI itself).

Installation

Recommended: Via HTTPeep Desktop App

When you install HTTPeep desktop app, httpeep-cli is bundled automatically. The app installs the CLI to a location in your PATH during first launch.

Verify it's available:

httpeep-cli --version

Fixing PATH Issues

If the CLI was installed but isn't found in your shell:

Open HTTPeep → Settings → MCP
Click Repair CLI / PATH Installation
Restart your terminal

Or via MCP tool:

# Using the MCP directly
httpeep_mcp_repair_cli_path_installation

Global Flags

These flags work with every command:

| Flag | Description | Default | |------|-------------|---------| | --format <fmt> | Output format: table, json, jsonl, csv | table | | --quiet / -q | Suppress headers and decorations | false | | --verbose / -v | Show debug output and timing info | false | | --color | Force color output (even in pipes) | auto | | --no-color | Disable color output | — |

JSON Output Mode

Append --format json to any command for machine-readable output:

httpeep-cli sessions list --format json | jq '.[] | select(.status >= 400)'

Use --format jsonl (JSON Lines) for streaming output—one JSON object per line, useful for piping into log processors.

`proxy` — Proxy Lifecycle

Manage the HTTPeep proxy engine.

`proxy status`

httpeep-cli proxy status

Proxy:   running  (port 8080)
Paused:  no
Uptime:  2h 14m
Sessions: 847
System Proxy: enabled (HTTP + HTTPS)

`proxy start`

httpeep-cli proxy start
httpeep-cli proxy start --port 9090        # Use a different port
httpeep-cli proxy start --no-system-proxy  # Don't set system proxy

`proxy stop`

httpeep-cli proxy stop

Sessions are preserved. The proxy engine stops accepting new connections.

`proxy pause`

httpeep-cli proxy pause    # Pause traffic capture
httpeep-cli proxy resume   # Resume traffic capture

Pausing keeps the proxy running but stops logging new sessions. Useful when you want to reduce noise during a specific operation.

`proxy restart`

httpeep-cli proxy restart

`sessions` — Session Queries

`sessions list`

List captured sessions with optional filters:

httpeep-cli sessions list
httpeep-cli sessions list --host api.example.com
httpeep-cli sessions list --status 4xx
httpeep-cli sessions list --status 500-599
httpeep-cli sessions list --method POST
httpeep-cli sessions list --path /api/v2
httpeep-cli sessions list --limit 50
httpeep-cli sessions list --since 5m         # Last 5 minutes
httpeep-cli sessions list --since 2026-04-13T10:00:00Z

Output (table format):

ID           METHOD  URL                                    STATUS  DURATION
abc123def4   POST    https://api.example.com/v2/users       201     234ms
xyz789abc1   GET     https://api.example.com/v2/users/001   200     45ms
err456def7   GET     https://api.example.com/v2/reports     500     1840ms

`sessions get <id>`

Get full session detail including headers and body:

httpeep-cli sessions get abc123def4
httpeep-cli sessions get abc123def4 --format json

=== REQUEST ===
POST https://api.example.com/v2/users HTTP/1.1
Content-Type: application/json
Authorization: [MASKED]

{"name": "Alice", "email": "alice@example.com"}

=== RESPONSE ===
HTTP/1.1 201 Created
Content-Type: application/json

{"id": "usr_001", "name": "Alice"}

=== TIMING ===
DNS:      12ms
Connect:  45ms
TLS:      38ms
TTFB:     180ms
Total:    234ms

`sessions watch`

Stream new sessions to stdout in real time:

httpeep-cli sessions watch
httpeep-cli sessions watch --host api.example.com
httpeep-cli sessions watch --format jsonl    # Machine-readable stream

Press Ctrl+C to stop.

`sessions delete <id>`

Delete a specific session:

httpeep-cli sessions delete abc123def4

`sessions clear`

Clear all captured sessions:

httpeep-cli sessions clear
httpeep-cli sessions clear --before 1h     # Clear sessions older than 1 hour
httpeep-cli sessions clear --confirm       # Skip the confirmation prompt

`request` — Send HTTP Requests Through the Proxy

Send HTTP requests through the HTTPeep proxy so they appear in the session list. Useful for testing without configuring a separate HTTP client.

httpeep-cli request GET https://api.example.com/v2/users
 
httpeep-cli request POST https://api.example.com/v2/users \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer token123" \
  --body '{"name": "Alice"}'
 
httpeep-cli request GET https://api.example.com/v2/users \
  --format json    # Get response as JSON

This is particularly useful for AI agents: instead of configuring curl to route through the proxy, they can use this command directly and the request will automatically appear in the session list for inspection.

`replay` — Replay Captured Requests

Re-send a previously captured request, optionally with modifications:

# Replay exactly as captured
httpeep-cli replay abc123def4
 
# Replay with a different auth token
httpeep-cli replay abc123def4 \
  --header "Authorization: Bearer new-token"
 
# Replay with a modified body
httpeep-cli replay abc123def4 \
  --body '{"name": "Bob"}'
 
# Replay against a different host
httpeep-cli replay abc123def4 \
  --host staging-api.example.com

The replayed request appears as a new session in the list.

`record` — Record Traffic as a Script

Record a sequence of sessions into a replayable script file:

# Record the next 10 sessions
httpeep-cli record --count 10 --output test-flow.httpeep
 
# Record for 30 seconds
httpeep-cli record --duration 30s --output test-flow.httpeep
 
# Record filtered traffic
httpeep-cli record --host api.example.com --output api-test.httpeep

Replay a recorded script:

httpeep-cli record replay test-flow.httpeep
 
# Replay against a different base URL
httpeep-cli record replay test-flow.httpeep \
  --base-url https://staging-api.example.com

This enables a record-once, replay-many pattern for regression testing.

`rules` — Forward Rule Management

Manage traffic routing rules.

# List all rules
httpeep-cli rules list
 
# Add a redirect rule
httpeep-cli rules add \
  --name "Staging redirect" \
  --match-host "api.myapp.com" \
  --action forward \
  --target "staging-api.myapp.com:443"
 
# Delete a rule
httpeep-cli rules delete rule-001
 
# Test whether a URL matches any rule
httpeep-cli rules test --url "https://api.myapp.com/v2/users" --method GET
 
# Export rules to file
httpeep-cli rules export --output rules-backup.json
 
# Import rules from file
httpeep-cli rules import rules-backup.json
 
# Reset to empty ruleset
httpeep-cli rules reset --confirm

`cert` — Certificate Management

# Check certificate status
httpeep-cli cert status
 
# Install and trust the root CA
httpeep-cli cert install

cert status output:

Root CA:      exists
OS Trust:     trusted ✓
Expires:      2028-04-13 (in 730 days)
Fingerprint:  SHA256:abc123...

`mcp` — MCP Service Management

`mcp serve`

Start the MCP stdio server (normally handled automatically by your AI agent's MCP configuration):

httpeep-cli mcp serve

`mcp doctor`

Diagnose MCP connectivity issues:

httpeep-cli mcp doctor

MCP Doctor Report
─────────────────────────────────────────────
✓ httpeep-cli found at /usr/local/bin/httpeep-cli (v0.8.4)
✓ Proxy engine reachable (port 8080)
✓ MCP service responding
✓ stdio transport: OK
✓ LAN service: running on port 9090
─────────────────────────────────────────────
All checks passed.

`monitor` — Real-Time Terminal Dashboard

Launch an interactive terminal dashboard showing live traffic:

httpeep-cli monitor
httpeep-cli monitor --host api.example.com   # Filter to specific host

The monitor shows:

Live session stream with status codes color-coded
Request rate (req/s)
Error rate
Top hosts by request count
Slowest endpoints in current window

Press q to exit, f to change filters, ? for help.

Practical Examples

CI: Capture API Traffic During Integration Tests

#!/bin/bash
set -e
 
# Start proxy
httpeep-cli proxy start --no-system-proxy
 
# Run tests with proxy configured
HTTP_PROXY=http://localhost:8080 \
HTTPS_PROXY=http://localhost:8080 \
npm test
 
# Save test run results
httpeep-cli sessions list --since 10m --format json > test-traffic.json
 
# Check for any 5xx errors
ERRORS=$(httpeep-cli sessions list --status 500-599 --since 10m --format json | jq length)
if [ "$ERRORS" -gt 0 ]; then
  echo "ERROR: $ERRORS server errors detected during test run"
  httpeep-cli sessions list --status 500-599 --since 10m
  exit 1
fi
 
echo "All API calls succeeded"
httpeep-cli proxy stop

Automated Testing: Record and Replay

#!/bin/bash
# Day 1: Record baseline
httpeep-cli sessions clear --confirm
npm run integration-tests
httpeep-cli record --since 5m --output baseline.httpeep
echo "Baseline recorded: $(httpeep-cli sessions list --since 5m --format json | jq length) sessions"
 
# Day 2+: Replay and verify behavior is unchanged
httpeep-cli record replay baseline.httpeep --compare

Parse JSON Output with jq

# Find all slow requests (>500ms)
httpeep-cli sessions list --since 1h --format json | \
  jq '.[] | select(.duration_ms > 500) | {url, status, duration_ms}'
 
# Get error rate
httpeep-cli sessions list --format json | \
  jq '{ total: length, errors: [.[] | select(.status >= 400)] | length } |
       .error_rate = (.errors / .total * 100 | round)'
 
# Extract unique hosts
httpeep-cli sessions list --format json | jq '[.[].host] | unique | sort[]'
 
# Find requests with large response bodies
httpeep-cli sessions list --format json | \
  jq '.[] | select(.response_size_bytes > 102400) |
      {url, response_size_kb: (.response_size_bytes / 1024 | round)}'

Output Format Reference

| Format | Description | Best For | |--------|-------------|----------| | table | Human-readable aligned columns | Interactive terminal use | | json | JSON array of objects | Scripting, jq pipelines | | jsonl | One JSON object per line | Streaming, log ingestion | | csv | Comma-separated values | Spreadsheet import |

Troubleshooting

`httpeep-cli: command not found`

Run httpeep-cli mcp repair_cli_path_installation from within the app, or go to Settings → MCP → Repair CLI / PATH. Then restart your terminal.

`Error: proxy engine not reachable`

The HTTPeep desktop app must be running for httpeep-cli to work. Start the app, then retry.

`Permission denied` on `cert install`

Certificate installation requires elevated privileges. Run:

sudo httpeep-cli cert install

Or use the desktop app's Settings → Certificate UI, which handles the privilege prompt automatically.

Sessions not appearing for my app

Check that your app is configured to use the proxy (HTTP_PROXY=http://localhost:8080), or that the system proxy is enabled (httpeep-cli proxy status). For HTTPS traffic, ensure the root CA is trusted (httpeep-cli cert status).

Output is garbled in CI logs

Use --no-color --format json in CI environments to get clean, machine-parseable output without ANSI escape codes.

For integrating httpeep-cli with AI agents via MCP, see Give Your AI Agent Network Vision. For the complete MCP tool reference, see HTTPeep MCP Complete Reference.

What is httpeep-cli?

Installation

Recommended: Via HTTPeep Desktop App

Fixing PATH Issues

Global Flags

JSON Output Mode

proxy — Proxy Lifecycle

proxy status

proxy start

proxy stop

proxy pause

proxy restart

sessions — Session Queries

sessions list

sessions get <id>

sessions watch

sessions delete <id>

sessions clear

request — Send HTTP Requests Through the Proxy

replay — Replay Captured Requests

record — Record Traffic as a Script

rules — Forward Rule Management

cert — Certificate Management

mcp — MCP Service Management

mcp serve

mcp doctor

monitor — Real-Time Terminal Dashboard