Skip to content

CLI Reference

httptape includes a standalone CLI binary for HTTP traffic recording, redaction, and replay. It is a thin wrapper over the httptape library and works with any language or framework via HTTP.

Install

go install github.com/httptape/httptape/cmd/httptape@latest

Or use the Docker image.

Commands

serve

Replay recorded fixtures as a mock HTTP server.

httptape serve --fixtures ./fixtures [flags]
Flag Default Description
--fixtures (required) Path to fixture directory
--port 8081 Listen port
--fallback-status 404 HTTP status when no tape matches
--cors false Enable CORS headers (Access-Control-Allow-Origin: *)
--delay 0 Fixed delay before every response (e.g., 200ms, 1s)
--error-rate 0 Fraction of requests that return 500 (0.0-1.0)
--replay-header (none) Header to inject into responses (Key=Value, repeatable)
--sse-timing (none) SSE replay timing mode: realtime, instant, accelerated=<factor>. When unset, the library default (realtime) is used.
--synthesize false Enable synthesis mode. When enabled, exemplar tapes (with "exemplar": true and a url_pattern) generate responses for unmatched URLs. See Synthesis.
--config (none) Path to httptape config JSON. When the config includes a matcher section, the server uses it to build a CompositeMatcher instead of the default method + path matcher. Sanitization rules in the config are ignored by serve. See Config.
--tls-listener-cert (none) Path to PEM certificate for inbound TLS. See TLS.
--tls-listener-key (none) Path to PEM private key for inbound TLS. See TLS.
--tls-listener-auto false Generate a self-signed cert at startup. See TLS.
--tls-listener-san localhost,127.0.0.1,::1 Comma-separated SANs for auto-cert (requires --tls-listener-auto).

The server uses DefaultMatcher (method + path matching) unless a --config with a matcher section is provided. Fixtures are loaded from the specified directory. The server shuts down gracefully on SIGINT/SIGTERM. At startup, all loaded tapes are validated; invalid exemplar tapes cause a startup error.

Example:

httptape serve --fixtures ./testdata/fixtures --port 9090 --fallback-status 502

record

Proxy requests to an upstream server, record and redact responses.

httptape record --upstream <url> --fixtures <dir> [flags]
Flag Default Description
--upstream (required) Upstream URL (e.g., https://api.example.com)
--fixtures (required) Path to fixture directory
--config (none) Path to redaction config JSON
--port 8081 Listen port
--cors false Enable CORS headers
--tls-cert (none) Path to PEM client certificate for mTLS. See TLS.
--tls-key (none) Path to PEM client private key for mTLS. See TLS.
--tls-ca (none) Path to PEM CA certificate(s) for upstream verification. See TLS.
--tls-insecure false Skip TLS verification (development only). See TLS.
--tls-listener-cert (none) Path to PEM certificate for inbound TLS. See TLS.
--tls-listener-key (none) Path to PEM private key for inbound TLS. See TLS.
--tls-listener-auto false Generate a self-signed cert at startup. See TLS.
--tls-listener-san localhost,127.0.0.1,::1 Comma-separated SANs for auto-cert (requires --tls-listener-auto).

The recorder starts a reverse proxy on the specified port. All requests are forwarded to the upstream, and responses are recorded (with optional redaction) to the fixtures directory.

The upstream URL must include the scheme and host (e.g., https://api.example.com).

Example:

httptape record \
  --upstream https://api.github.com \
  --fixtures ./fixtures \
  --config redact.json \
  --port 8081

Then point your application at http://localhost:8081 instead of the real API. All traffic is recorded and redacted.

proxy

Forward requests to an upstream server with two-tier caching and automatic fallback. The proxy subcommand uses Proxy, which composes CachingTransport internally for upstream forwarding, sanitization, and recording (since v0.13.1). See Proxy Mode for a full guide, or CachingTransport for the standalone library API.

httptape proxy --upstream <url> --fixtures <dir> [flags]
Flag Default Description
--upstream (required) Upstream URL (e.g., https://api.example.com)
--fixtures (required) Path to fixture directory for L2 (persistent) cache
--config (none) Path to redaction config JSON (applied to L2 writes only)
--port 8081 Listen port
--cors false Enable CORS headers
--fallback-on-5xx false Also fall back on 5xx responses from upstream
--sse-timing (none) SSE replay timing mode for L2 fallback: realtime, instant, accelerated=<factor>. When unset, the library default (instant) is used.
--tls-cert (none) Path to PEM client certificate for mTLS. See TLS.
--tls-key (none) Path to PEM client private key for mTLS. See TLS.
--tls-ca (none) Path to PEM CA certificate(s) for upstream verification. See TLS.
--tls-insecure false Skip TLS verification (development only). See TLS.
--tls-listener-cert (none) Path to PEM certificate for inbound TLS. See TLS.
--tls-listener-key (none) Path to PEM private key for inbound TLS. See TLS.
--tls-listener-auto false Generate a self-signed cert at startup. See TLS.
--tls-listener-san localhost,127.0.0.1,::1 Comma-separated SANs for auto-cert (requires --tls-listener-auto).

When the upstream is reachable, requests are forwarded and responses are cached:

  • L1 (memory): raw, unsanitized responses for best within-session fidelity
  • L2 (disk): redacted responses that persist across restarts

When the upstream is unreachable (or returns 5xx with --fallback-on-5xx), the proxy serves cached responses. The X-Httptape-Source header indicates whether a response came from l1-cache, l2-cache, or the real upstream (header absent).

Example:

httptape proxy \
  --upstream https://api.staging.example.com \
  --fixtures ./cache \
  --config redact.json \
  --port 3001 \
  --cors \
  --fallback-on-5xx

export

Export fixtures to a tar.gz bundle.

httptape export --fixtures <dir> [flags]
Flag Default Description
--fixtures (required) Path to fixture directory
--output stdout Output file path
--routes (none) Comma-separated route filter
--methods (none) Comma-separated HTTP method filter
--since (none) RFC 3339 timestamp filter

Examples:

# Export all fixtures to a file
httptape export --fixtures ./fixtures --output bundle.tar.gz

# Export only GET requests to the users-api route
httptape export --fixtures ./fixtures --output users.tar.gz \
  --routes users-api --methods GET

# Export fixtures recorded after a specific date
httptape export --fixtures ./fixtures --output recent.tar.gz \
  --since 2024-01-01T00:00:00Z

# Export to stdout (pipe to another tool)
httptape export --fixtures ./fixtures | gzip -d | tar -tf -

import

Import fixtures from a tar.gz bundle.

httptape import --fixtures <dir> [flags]
Flag Default Description
--fixtures (required) Path to fixture directory
--input stdin Input file path

Existing fixtures with the same ID are overwritten. Fixtures not in the bundle are left untouched.

Examples:

# Import from a file
httptape import --fixtures ./fixtures --input bundle.tar.gz

# Import from stdin
cat bundle.tar.gz | httptape import --fixtures ./fixtures

migrate-fixtures

Migrate fixtures from v0.11 format (base64-encoded bodies with body_encoding field) to v0.12 format (Content-Type-driven body shape).

httptape migrate-fixtures [--recursive] <dir>
Flag Default Description
--recursive false Recurse into subdirectories

The migration tool: - Reads each .json file in <dir> - Skips non-tape JSON files (files that don't parse as valid Tape objects) - Decodes base64-encoded bodies using the legacy body_encoding field - Re-serializes the tape with the new Content-Type-aware body shape - Removes the body_encoding field - Prints a summary of migrated, skipped, and errored files

The tool is idempotent: running it on already-migrated fixtures produces the same output.

Examples:

# Migrate a flat fixtures directory
httptape migrate-fixtures ./fixtures

# Migrate recursively (e.g., route-based subdirectories)
httptape migrate-fixtures --recursive ./fixtures

# Migrate example project fixtures
httptape migrate-fixtures --recursive ./examples/java-spring-boot/src/test/resources/fixtures/

Exit codes

Code Meaning
0 Success
1 Usage error (bad flags, missing required args)
2 Runtime error (server failure, store error)

Signal handling

The serve, record, and proxy commands handle SIGINT and SIGTERM for graceful shutdown:

  1. Stop accepting new connections
  2. Wait up to 5 seconds for in-flight requests
  3. In record mode, flush pending recordings
  4. Exit

Typical workflow

# 1. Record traffic from a real API (with redaction)
httptape record \
  --upstream https://api.example.com \
  --fixtures ./fixtures \
  --config redact.json

# 2. Export the fixtures
httptape export --fixtures ./fixtures --output fixtures.tar.gz

# 3. Import on another machine / in CI
httptape import --fixtures ./ci-fixtures --input fixtures.tar.gz

# 4. Serve the fixtures as a mock
httptape serve --fixtures ./ci-fixtures --port 8081

See also