These options control how hitspec’s HTTP client behaves for a whole run. Each one is a hitspec run flag, a HITSPEC_* environment variable and a hitspec.yaml key; the same keys apply when the client is driven by hitspec studio, hitspec serve, --stress and hitspec contract.
Precedence is the usual one: flag, then environment variable, then hitspec.yaml, then the default.
Private CAs
--cacert adds a PEM bundle to the system roots, so an API served with a company or test CA is verified instead of being run with --insecure.
Mutual TLS
Give both halves of the client certificate:
A certificate without a key (or the reverse), or a file that is missing or is not valid PEM, stops the run before any request is sent. hitspec prints the error, naming the file, and exits with code 3.
In hitspec.yaml
Relative paths for cacert, cert and key are resolved against the directory of the hitspec.yaml they are written in, not the directory you run hitspec from. Paths given as flags or environment variables are relative to the working directory.
HTTP/1.1 only
By default hitspec negotiates HTTP/2 over TLS. --http1.1 turns that off, which helps when a proxy or server misbehaves on HTTP/2 or when you want to reproduce an HTTP/1.1 client.
Cookies
Cookies are off by default: a Set-Cookie response header is not sent back on later requests. --cookies gives the run a cookie jar, so a login request can start a session that the requests after it use. The jar is shared by every file in the run and starts empty each time you run hitspec. With --watch the same jar is kept across re-runs, so a session started by one run is still there in the next.
Turn it back off for one run with --cookies=false when hitspec.yaml enables it.
Response size limit
A response body larger than 100 MiB fails the request. --max-response-bytes changes the limit; -1 removes it. The limit applies to the bytes on the wire and to the decoded size of a gzip or deflate response.
Redirects and your headers
When a redirect goes to a different origin (scheme, host or port), hitspec drops the headers you set on the request, such as API keys and Authorization, so they are not leaked to another site. Content negotiation headers (Accept, Content-Type, User-Agent, …) are kept. --redirect-forward-headers keeps all of them; use it only for redirects you trust. Last modified on October 19, 2026
