CLI Integration

The TraceCov CLI generates coverage reports from recorded API traffic and can act as a proxy to capture live traffic.

Installation

curl -sL https://cli.tracecov.sh/install/ | sh
chmod +x tracecov

Basic Usage

Generate an HTML report from JSON traffic data:

tracecov report openapi.json traffic.json

This creates coverage.html by default. Use -o to specify a different path.

Traffic Format

Example traffic file:

{
  "interactions": [
    {
      "request": {
        "method": "GET",
        "url": "https://api.example.com/users/1",
        "headers": {}
      },
      "response": {
        "status_code": 200,
        "elapsed": 0.05
      },
      "timestamp": 1700000000.0
    }
  ]
}

Each interaction contains a request, an optional response, and an optional timestamp:

Field	Type	Required	Description
request.method	string	Yes	HTTP method (GET, POST, PUT, DELETE, etc.)
request.url	string	Yes	Full URL including query parameters
request.headers	object	No	HTTP headers as key-value pairs
request.body	string	No	Request body as UTF-8 text
request.body_base64	string	No	Request body as base64-encoded binary
response.status_code	integer	No	HTTP status code
response.elapsed	float	No	Response time in seconds
timestamp	float	No	Unix timestamp in seconds

Body Encoding

Use body for text content (JSON, XML, form data):

{
  "request": {
    "method": "POST",
    "url": "https://api.example.com/users",
    "body": "{\"name\": \"Alice\", \"email\": \"alice@example.com\"}",
    "headers": {"Content-Type": "application/json"}
  }
}

Use body_base64 for binary content (images, files):

{
  "request": {
    "method": "POST",
    "url": "https://api.example.com/upload",
    "body_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...",
    "headers": {"Content-Type": "image/png"}
  }
}

Omit both fields for requests without a body (GET, DELETE).

Output Formats

HTML (default) - Interactive coverage report, writes to coverage.html:

tracecov report openapi.json traffic.json

JSON - Machine-readable output for CI (see JSON Report Format for schema and jq recipes):

# Output to stdout (for piping to jq)
tracecov report openapi.json traffic.json --format json

# Use in CI scripts
tracecov report openapi.json traffic.json --format json | jq '.summary.operations'

# Save to file
tracecov report openapi.json traffic.json --format json -o coverage.json

Coverage Thresholds

Fail the build if coverage is below a threshold:

# Fail if any metric is below 80%
tracecov report openapi.json traffic.json --fail-under 80

# Per-metric thresholds
tracecov report openapi.json traffic.json \
  --fail-under-operations 90 \
  --fail-under-parameters 70

# Base threshold with override
tracecov report openapi.json traffic.json --fail-under 80 --fail-under-operations 95

Available flags:

• --fail-under
• --fail-under-operations
• --fail-under-parameters
• --fail-under-keywords
• --fail-under-examples
• --fail-under-responses

Also works with tracecov proxy.

Exit codes: 0 = success, 1 = threshold not met or error.

Professional Features

Professional Edition

The following features require TraceCov Professional.

Proxy Mode

Capture traffic from any HTTP client by running a local proxy:

# Start the proxy (runs until Ctrl+C)
tracecov proxy openapi.json -p 8080

Configure your HTTP client to use the proxy, then run your tests. Most clients respect standard environment variables:

# Set proxy for all HTTP clients
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080

# Run your tests
pytest tests/

Or configure directly in your code:

# httpx
httpx.get("https://api.example.com/users", proxy="http://localhost:8080")

# requests
requests.get("https://api.example.com/users", proxies={"all": "http://localhost:8080"})

Or per-request in shell:

# curl (use -k to skip certificate verification, or --cacert for the CA)
curl -k --proxy http://localhost:8080 https://api.example.com/users

Press Ctrl+C to stop the proxy. TraceCov generates coverage.html with all captured traffic.

Use -v to see each request as it's proxied:

tracecov proxy openapi.json -v

HTTPS Traffic

The proxy intercepts HTTPS by generating certificates on-the-fly. Your HTTP client must trust the proxy's CA certificate, or you'll get TLS errors.

The CA certificate is exported to /tmp/tracecov-ca.pem by default (use --export-ca for a custom path).

Quick options:

# curl: trust the CA
curl --cacert /tmp/tracecov-ca.pem --proxy http://localhost:8080 https://api.example.com

# curl: skip verification
curl -k --proxy http://localhost:8080 https://api.example.com

# Python requests
session.verify = "/tmp/tracecov-ca.pem"

# Python httpx
client = httpx.Client(verify="/tmp/tracecov-ca.pem", proxy="http://localhost:8080")

Base Path Matching

Use --base-path to specify the URL prefix that maps to your schema's root. This is needed when requests go to a full URL but your schema paths are relative:

# Schema has paths like /users, /pets
# Requests go to https://api.example.com/v1/users
tracecov proxy openapi.json --base-path https://api.example.com/v1

Without --base-path, the proxy matches request paths directly against schema paths.

Traffic Imports

Professional Edition

The Professional edition supports HAR files, Postman collections, and VCR cassettes out of the box:

tracecov report openapi.json traffic.har