BlogHomepageDownload

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 list

Filter flags:

FlagDescriptionExample
--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-pinnedOnly pinned sessions--is-pinned
--is-importantOnly 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 login

Example 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

To 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 login

Use --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 def456

Delete 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 login

sessions 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 --yes

sessions 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})'

On this page

sessions listsessions watchsessions deletesessions clearjq pipeline examples