httpeep-cli: command-line interface overview
httpeep-cli gives full programmatic access to the HTTPeep proxy engine — capture traffic, query sessions, manage rules, and replay requests from a terminal.
httpeep-cli is the command-line interface for HTTPeep. It exposes the full feature set of the proxy engine — capturing traffic, querying sessions, managing rules, and replaying requests — without requiring you to open the desktop UI.
There are three primary use cases for httpeep-cli:
- Script and CI integration — start the proxy, run your test suite, capture sessions, and query them programmatically from shell scripts or pipeline steps
- AI agent workflows — structured JSON output makes captured traffic easy for tools like Claude or Codex to parse and reason about
- Power user workflows — record/replay sessions, bulk-manage rules, and monitor live traffic from an interactive terminal dashboard
Installation
httpeep-cli is bundled with the HTTPeep desktop app. When you install HTTPeep, the CLI is placed on your PATH automatically during first launch. No separate install step is needed.
Verify the CLI is available:
httpeep-cli --versionhp is available as a short alias for interactive use. Documentation and automation examples use the full httpeep-cli command for clarity.
You can also build and install it from source:
# In the project root
cargo build --package httpeep-cli --manifest-path ./apps/cli/Cargo.toml
# Install to ~/.cargo/bin/httpeep-cli
bun run install_cliFixing PATH issues
If the CLI is installed but your shell can't find it:
Go to Settings → MCP in the desktop app.
Click Repair CLI / PATH Installation.
Open a new terminal window and run httpeep-cli --version to confirm the fix.
You can also trigger the repair from within an MCP-connected AI agent by calling the httpeep_mcp_repair_cli_path_installation tool directly.
Global flags
These flags work with every httpeep-cli command.
| Flag | Description | Default |
|---|---|---|
--format <fmt> | Output format: human, json, or table | human |
--quiet / -q | Suppress informational messages | — |
--verbose / -v | Enable verbose output | — |
--color <mode> | Color output: auto, always, or never | auto |
-h, --help | Print help | — |
-V, --version | Print version | — |
Output formats
Every command that produces tabular output supports three formats. Choose the format that fits your workflow.
| Format | Description | Best for |
|---|---|---|
human | Human-readable plain text | Interactive terminal use |
json | JSON array or object | Scripting and jq pipelines |
table | Aligned columns with borders | Quick overview in terminal |
Append --format <fmt> to any command to switch formats:
httpeep-cli sessions list --format json
httpeep-cli rules list --format table
httpeep-cli proxy statussessions watch with --format json outputs NDJSON (one JSON object per line), which is ideal for streaming pipelines.
JSON output and jq pipelines
Use --format json with jq to build powerful one-liners over your captured traffic.
# Filter to only failed requests
httpeep-cli sessions list --format json | jq '.[] | select(.status >= 400)'
# Find slow requests (over 500 ms)
httpeep-cli sessions list --format json | \
jq '.[] | select(.duration_ms > 500) | {url, status, duration_ms}'
# Compute error rate
httpeep-cli sessions list --format json | \
jq '{ total: length, errors: [.[] | select(.status >= 400)] | length } |
.error_rate = (.errors / .total * 100 | round)'
# List unique hosts
httpeep-cli sessions list --format json | jq '[.[].host] | unique | sort[]'
# Find responses with large bodies (over 100 KB)
httpeep-cli sessions list --format json | \
jq '.[] | select(.response_size_bytes > 102400) |
{url, response_size_kb: (.response_size_bytes / 1024 | round)}'In CI environments, use --format json together to get clean, machine-parseable output with no ANSI escape codes in your logs.