Sessions
Query and inspect captured traffic. List, filter, watch, and delete captured HTTP sessions from the command line. Combine with jq for powerful scripting and CI traffic analysis.
The sessions subcommand lets you query every HTTP and HTTPS request that HTTPeep has captured. You can filter sessions by host, status code, HTTP method, path, or time window; inspect the full request and response of any session including headers, body, and timing breakdown; stream new sessions in real time; or clear old sessions to keep your workspace clean.
sessions list
List captured sessions with optional filters. With no flags, returns all sessions in the current session store.
httpeep-cli sessions listFilter flags:
| Flag | Description | Example |
|---|---|---|
--id <id> | Filter by exact session ID | --id abc123 |
--method <method> | Filter by HTTP method | --method POST |
--status-code <code> | Filter by status code | --status-code 200 |
--process-id <pid> | Filter by process ID | --process-id 1234 |
--domain <domain> | Filter by domain | --domain api.example.com |
--client-ip <ip> | Filter by client IP | --client-ip 127.0.0.1 |
--is-pinned | Only pinned sessions | --is-pinned |
--is-important | Only important sessions | --is-important |
--from-ts <ts> | Sessions captured after timestamp | --from-ts 1713000000 |
--to-ts <ts> | Sessions captured before timestamp | --to-ts 1714000000 |
--url-like <pattern> | Fuzzy match URL | --url-like "/api" |
--path-like <pattern> | Fuzzy match path | --path-like "/v2" |
--domain-like <pattern> | Fuzzy match domain | --domain-like "example" |
--process-name-like <pattern> | Fuzzy match process name | --process-name-like "curl" |
--keyword <keyword> | Keyword search across URL, domain, method, status, and process name | --keyword login |
# Filter examples
httpeep-cli sessions list --method POST --status-code 200
httpeep-cli sessions list --domain api.example.com
httpeep-cli sessions list --keyword login
httpeep-cli sessions list --url-like "/api" --process-name-like "curl"JSON output for scripting:
httpeep-cli --format json sessions list --keyword loginExample 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 1840msTo get the full detail of a single session, use sessions list --id <session_id> with --format json to see headers, body, and timing.
sessions watch
Stream new sessions to stdout in real time as they are captured. Press Ctrl+C to stop.
httpeep-cli sessions watch
# Filter the stream to a specific domain
httpeep-cli sessions watch --domain api.example.com
# Machine-readable stream — one JSON object per line (NDJSON)
httpeep-cli --format json sessions watch --keyword loginUse --format json when piping the stream into a log processor or another tool. Each captured session is emitted as a single self-contained JSON object on its own line.
All filter flags from sessions list also work with watch.
sessions delete
Delete sessions by specific IDs or by query conditions.
Delete by IDs:
httpeep-cli sessions delete --id abc123 --id def456Delete by query conditions (with a dry-run preview first):
# Preview what would be deleted
httpeep-cli sessions delete --keyword login --dry-run
# Execute the deletion
httpeep-cli sessions delete --keyword loginsessions clear
Clear all sessions from the session store.
# Preview before clearing
httpeep-cli sessions clear --all --yes --dry-run
# Execute
httpeep-cli sessions clear --all --yessessions clear --all --yes permanently deletes all sessions without prompting. Use this flag in scripts only when you are certain you no longer need the captured data.
jq pipeline examples
Use --format json with jq to analyze captured traffic programmatically.
# Find all slow requests (over 500 ms)
httpeep-cli sessions list --format json | \
jq '.[] | select(.duration_ms > 500) | {url, status, duration_ms}'
# Compute error rate across all captured sessions
httpeep-cli sessions list --format json | \
jq '{ total: length, errors: [.[] | select(.status >= 400)] | length } |
.error_rate = (.errors / .total * 100 | round)'
# List unique hosts seen in the last hour
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)}'
# Count requests by HTTP method
httpeep-cli sessions list --format json | \
jq 'group_by(.method) | map({method: .[0].method, count: length})'