Skip to content

cli.md

Latest commit

 

History

History
453 lines (311 loc) · 13.5 KB

cli.md

File metadata and controls

453 lines (311 loc) · 13.5 KB
Raw

CLI Reference

reqlog ships with a command-line interface for querying, tailing, and exporting HTTP request logs stored in a SQLite database. The CLI is powered by Click and uses Rich for colored terminal output.

Installation

The reqlog CLI is installed automatically when you install the package:

pip install reqlog

Verify the installation:

reqlog --version

The CLI requires that your application is using SQLiteBackend to persist request logs. See Backends for setup instructions.

Commands

reqlog tail

Live-tail HTTP request logs from a SQLite database. Displays recent entries, then polls for new ones every 500ms until interrupted with Ctrl+C.

Usage:

reqlog tail [OPTIONS]

Options:

Option Type Default Description
--db string reqlog.db Path to the SQLite database file.
--status integer (none) Filter by exact HTTP status code.
--path string (none) Filter by path substring match.
--method string (none) Filter by HTTP method (case-insensitive).
--slow float (none) Show only requests slower than N milliseconds.
--limit integer 50 Number of recent entries to show initially.

How it works:

  1. On startup, tail fetches the most recent entries (controlled by --limit) and prints them oldest-first.
  2. It then enters a polling loop, querying for any rows with a timestamp newer than the last seen entry.
  3. New rows are printed immediately in compact colored format. Press Ctrl+C to stop; a total count is printed on exit.

Output format:

Each line uses the compact formatter style with color-coded elements:

  ● GET     /api/users                                     200    12ms   14:23:46
  ● POST    /api/users                                     201    45ms   14:23:47
  ● GET     /api/users/42                                  200     8ms   14:23:48
  ● DELETE  /api/users/42                                  204    23ms   14:23:49
  ● GET     /api/missing                                   404     3ms   14:23:50
  x POST    /api/crash                                     500   312ms   14:23:51
  • Status glyphs: a filled circle for 2xx/3xx/4xx, an "x" for 5xx.
  • Methods are color-coded: GET in blue, POST in green, DELETE in red, PUT/PATCH in yellow.
  • Timing is green under 100ms, yellow under 500ms, red above 500ms.
  • Paths longer than 45 characters are truncated with an ellipsis.

Examples:

Tail all requests:

reqlog tail

Tail only server errors:

reqlog tail --status 500

Tail slow requests on API endpoints:

reqlog tail --path /api --slow 200

Tail only POST requests from a custom database:

reqlog tail --db /var/log/myapp.db --method POST

Show the last 200 entries initially, then continue tailing:

reqlog tail --limit 200

reqlog stats

Display aggregated statistics from the request log database, including request counts, latency percentiles, status code breakdowns, method distributions, and the slowest endpoints.

Usage:

reqlog stats [OPTIONS]

Options:

Option Type Default Description
--db string reqlog.db Path to the SQLite database file.
--minutes integer 60 Time window in minutes to analyze.

Output sections:

  1. Summary -- Total requests, average duration, and latency percentiles (P50, P95, P99).
  2. Status Codes -- Rich table showing request counts per status class (2xx, 3xx, 4xx, 5xx).
  3. HTTP Methods -- Rich table showing request counts per method (GET, POST, etc.).
  4. Top 10 Slowest Endpoints -- Rich table showing method, path, count, average duration, and max duration for the slowest endpoint/method combinations.

Example output:

Request Stats (last 60 min)

  Total requests: 1,247
  Avg duration:   42.3ms
  P50:            28.1ms
  P95:            156.4ms
  P99:            512.7ms

         Status Codes
  ┌───────┬───────┐
  │ Class │ Count │
  ├───────┼───────┤
  │ 2xx   │ 1,102 │
  │ 3xx   │    45 │
  │ 4xx   │    89 │
  │ 5xx   │    11 │
  └───────┴───────┘

         HTTP Methods
  ┌────────┬───────┐
  │ Method │ Count │
  ├────────┼───────┤
  │ DELETE │    23 │
  │ GET    │   876 │
  │ PATCH  │    54 │
  │ POST   │   294 │
  └────────┴───────┘

       Top 10 Slowest Endpoints
  ┌────────┬──────────────────┬───────┬──────────┬──────────┐
  │ Method │ Path             │ Count │ Avg (ms) │ Max (ms) │
  ├────────┼──────────────────┼───────┼──────────┼──────────┤
  │ POST   │ /api/reports     │    12 │    523.4 │   1245.0 │
  │ GET    │ /api/search      │   134 │    312.1 │    890.3 │
  │ POST   │ /api/upload      │     8 │    287.6 │    654.2 │
  └────────┴──────────────────┴───────┴──────────┴──────────┘

Examples:

Stats for the last hour (default):

reqlog stats

Stats for the last 24 hours:

reqlog stats --minutes 1440

Stats from a specific database:

reqlog stats --db /var/log/myapp.db --minutes 30

reqlog export

Export HTTP request logs to JSON (JSON-Lines) or CSV format. Output is written to stdout, making it easy to pipe to other tools.

Usage:

reqlog export [OPTIONS]

Options:

Option Type Default Description
--db string reqlog.db Path to the SQLite database file.
--format choice json Output format: json or csv.
--since string (none) Filter entries since a time (ISO format or relative expression).
--status integer (none) Filter by exact HTTP status code.
--path string (none) Filter by path substring match.
--method string (none) Filter by HTTP method.
--limit integer 1000 Maximum number of entries to export.

Time parsing for --since:

The --since option accepts two formats:

  • ISO 8601: 2026-02-14T12:00:00 (interpreted as UTC if no timezone is provided)
  • Relative: "1 hour ago", "30 minutes ago", "2 days ago", "5 min ago"

JSON output:

Each line is a self-contained JSON object, one per request (JSON-Lines format):

reqlog export --format json --since "1 hour ago"
{"id": "a1b2c3d4e5f6", "timestamp": "2026-02-14T14:23:46+00:00", "method": "GET", "path": "/api/users", "query_string": null, "status_code": 200, "duration_ms": 12.34, "client_ip": "127.0.0.1", "user_agent": "curl/8.0"}
{"id": "f6e5d4c3b2a1", "timestamp": "2026-02-14T14:23:47+00:00", "method": "POST", "path": "/api/users", "query_string": null, "status_code": 201, "duration_ms": 45.67, "client_ip": "127.0.0.1", "user_agent": "curl/8.0"}

CSV output:

Exports a subset of fields with a header row:

reqlog export --format csv --since "1 hour ago"
id,timestamp,method,path,status_code,duration_ms,client_ip
a1b2c3d4e5f6,2026-02-14T14:23:46+00:00,GET,/api/users,200,12.34,127.0.0.1
f6e5d4c3b2a1,2026-02-14T14:23:47+00:00,POST,/api/users,201,45.67,127.0.0.1

Piping to other tools:

# Count 5xx errors in the last 6 hours
reqlog export --since "6 hours ago" --status 500 | wc -l

# Extract slow endpoint paths with jq
reqlog export --format json | jq -r 'select(.duration_ms > 500) | .path'

# Import into pandas
reqlog export --format csv --limit 10000 > requests.csv

Examples:

Export all errors from the last day:

reqlog export --since "1 day ago" --status 500 --format json

Export POST requests to a CSV file:

reqlog export --method POST --format csv > posts.csv

Export the last 100 requests to a specific API path:

reqlog export --path /api/users --limit 100

reqlog mcp

Start the reqlog MCP server, exposing HTTP logs to AI coding agents (Claude Code, Cursor, etc.) via the Model Context Protocol. The server runs on stdio transport and provides structured tools for querying, searching, and summarizing request logs.

Usage:

reqlog mcp [OPTIONS]

Options:

Option Type Default Description
--db string .reqlog/reqlog.db Path to the SQLite database file.
--redact-bodies flag false Strip all request/response bodies from MCP responses.

Requires: The mcp optional dependency (pip install reqlog[mcp]).

Available tools:

Tool Description
get_recent_requests Fetch recent HTTP logs with filters for status, path, method, duration, and time window.
get_request_detail Full transaction details (headers + bodies) for a specific request ID.
get_error_summary Aggregated 4xx/5xx error report with breakdown by status code.
search_requests Full-text search across path, request body, response body, and headers.
get_endpoint_stats Per-endpoint performance stats with percentiles (p50, p95, p99).

Available resources:

Resource Description
reqlog://status Session summary: total requests, error rate, last error.
reqlog://recent-errors Last 5 error responses in compact format.

Editor integration:

Add reqlog to your editor's MCP config to give AI agents automatic access. For Claude Code (.mcp.json in your project root):

{
  "mcpServers": {
    "reqlog": {
      "command": "uvx",
      "args": ["reqlog", "mcp", "--db", "reqlog.db"]
    }
  }
}

For local development (when reqlog is not installed globally), use uv run instead of uvx:

{
  "mcpServers": {
    "reqlog": {
      "command": "uv",
      "args": ["run", "reqlog", "mcp", "--db", "reqlog.db"]
    }
  }
}

Examples:

Start the MCP server with default database path:

reqlog mcp

Start with a specific database and body redaction:

reqlog mcp --db /var/log/app/reqlog.db --redact-bodies

reqlog demo

Launch the built-in FastAPI demo application with reqlog middleware enabled. Useful for trying out the library without setting up your own application.

Usage:

reqlog demo [OPTIONS]

Options:

Option Type Default Description
--host string 127.0.0.1 Host to bind to.
--port integer 8000 Port to bind to.

Requires uvicorn to be installed (included in the dev dependencies).

reqlog demo --port 9000

Common Workflows

Monitor production errors

Use tail with a status filter to watch for server errors in real time:

reqlog tail --db /var/log/app/reqlog.db --status 500

Or watch for all client and server errors (combine with path filtering):

reqlog tail --status 404 --path /api

Debug slow endpoints

Identify requests taking longer than 500ms:

reqlog tail --slow 500

Get a statistical overview of the slowest endpoints over the last 2 hours:

reqlog stats --minutes 120

Export for analysis

Export the last 24 hours of data for offline analysis:

reqlog export --since "24 hours ago" --format json > logs.jsonl

Generate a quick CSV report of errors:

reqlog export --since "1 day ago" --status 500 --format csv > errors.csv

Give AI agents access to your logs

Configure your app with a SQLite backend, then start the MCP server:

reqlog mcp --db reqlog.db

Add the server to your editor's MCP config (.mcp.json). The AI agent can then query logs directly -- calling get_recent_requests() to see what happened, get_request_detail() to inspect a specific transaction, or get_error_summary() to understand what's broken.

For privacy-sensitive environments, use --redact-bodies to strip all request/response bodies:

reqlog mcp --db reqlog.db --redact-bodies

Combine filters

Tail slow POST requests to your API:

reqlog tail --method POST --path /api --slow 100

Export GET requests that returned 200 from a specific database:

reqlog export --db production.db --method GET --status 200 --limit 5000