Recording traffic

shell

resterm record --listen 127.0.0.1:9000 --upstream https://service.example.com --out captured.http --mode both

Point your application's API base URL at http://127.0.0.1:9000. Resterm forwards traffic to --upstream and writes recordings as requests finish. --mode accepts requests (default), mocks, or both. The output file must be new and its parent directory must exist. Ctrl+C allows active requests up to 3 seconds to finish.

In the TUI, run :record start --upstream https://service.example.com, view captures with :record list, and stop with :record stop. Use :record as-request or :record as-mock to insert all completed recordings into the current .http or .rest file. Pass a capture ID to insert one. The file must have a path, and each insertion can be undone. Save the file after inserting recordings. They count as exported only after saving.

Recordings stay in memory when you switch files. :record clear discards a stopped session. Resterm warns before quitting with active recording or unsaved captures. :q! discards them.

Redaction uses header and field names. Saved copies replace known credential headers and query, form, and JSON fields with REDACTED, and remove cookies. Repeat --redact-header or --redact-field to add names. Free text and values under unrecognized names are left unchanged, even if they contain tokens or passwords. Review recordings before sharing. Replace REDACTED request values with variables before replaying requests that need credentials. Forwarded traffic keeps its original credentials.

Use --skip and --only to choose what is recorded. Rules are [METHOD ]path with the path in the mock route syntax described under Route and response syntax, for example --skip "GET /health" or --only /api/{rest...}. Both flags can be repeated. --skip wins. Filtered requests are still forwarded and do not count as skipped captures, so they do not affect the exit status.

Supported bodies are empty, JSON, URL-encoded forms, and UTF-8 text. Gzip is decoded only in recorded copies. Bodies that would change when parsed as request-file syntax are saved in separate files in a resterm-record-* directory. Keep that directory beside the request file. Its bodies use the same redaction rules and are read as literal data, without running templates or includes.

Binary, multipart, unsupported encodings, malformed JSON, duplicate JSON keys, oversized bodies, and incomplete bodies cannot be exported. Resterm reports why an export was skipped. Forwarding continues. CONNECT tunnels and protocol upgrades are rejected. WebSocket, gRPC, and SSE recording are unsupported.

The listener uses HTTP. The upstream must be one HTTP(S) origin, such as https://service.example.com, without credentials, a path prefix, query, or fragment. TLS uses the system's trusted certificates. Environment proxy settings are ignored. Redirects, CORS, cookies, and response URLs are forwarded unchanged, so redirected requests may bypass the recorder.

Defaults are 1,000 recordings in memory, 64 MiB each for stored recordings and shared capture buffers, 4 MiB per body before and after decoding, and 32 simultaneous captures. Adjust these with --max-entries, --max-bytes, --body-limit, and --capture-concurrency. Limits can cause captures or exports to be skipped. Existing recordings are kept and forwarding continues. The CLI exits 0 on success, 1 if any requested capture or export was skipped or recording failed, and 2 for invalid arguments.

Generated requests use recordedBaseUrl. Change it to the mock server address for replay. Mocks match the method, path, query values that were not redacted, and JSON fields that were not redacted. Form and text bodies are not used for matching. When mocks match the same request, the first one wins. Use X-Resterm-Mock: <scenario-name> to select a particular response. Requests are named from the method and path, such as get-users-42, and carry a description with the capture ID, status, and timing. Each request asserts the recorded status code, except redirects, since resterm run follows them. Resterm does not create response sequences. Add more @assert and @expect rules as needed, then use resterm run and resterm mock verify.

For a local walkthrough, serve _examples/recording.http with resterm mock _examples/recording.http --addr 127.0.0.1:9001, record that origin on port 9000, and run resterm run _examples/recording.http. The example includes assertions and a mock call expectation.