hitspec run

Run HTTP API tests defined in .http or .hitspec files.

hitspec run <file|directory> [flags]

Arguments

Argument	Description
`<file>`	Single `.http` or `.hitspec` file to run
`<directory>`	Directory containing test files (searched recursively)
`<glob>`	A quoted pattern such as `'tests/*/.http'`
`-`	Read one document from stdin

You can pass multiple files, directories and patterns as arguments. See Inputs.

Flags

Core Flags

Flag	Short	Description	Default	Env Var
`--env`	`-e`	Environment name to use. Order: flag, then `HITSPEC_ENV`, then `defaultEnvironment` in `hitspec.yaml`, then `dev`	`defaultEnvironment`, else `dev`	`HITSPEC_ENV`
`--env-file`		Path to `.env` file for variable interpolation; a missing file is an error (exit code 3)		`HITSPEC_ENV_FILE`
`--config`		Path to config file (`hitspec.yaml`); default: the nearest one from the working directory upward		`HITSPEC_CONFIG`
`--name`	`-n`	Run only tests matching name pattern
`--tags`	`-t`	Run only tests with specified tags (comma-separated)		`HITSPEC_TAGS`

Output Flags

Flag	Short	Description	Default	Env Var
`--verbose`	`-v`	Verbose output, repeatable: `-v`, `-vv`, `-vvv` for more detail (see Verbose Output)	`false`
`--quiet`	`-q`	Suppress the report on stdout. Failures are still listed on stderr and `--output-file` is still written	`false`	`HITSPEC_QUIET`
`--no-color`		Disable colored output	`false`	`HITSPEC_NO_COLOR`
`--output`	`-o`	Output format: `console`, `json`, `junit`, `tap`, `html`. Overrides `reporters` and `outputDir` in `hitspec.yaml`	`console`	`HITSPEC_OUTPUT`
`--output-file`		Write output to a file instead of stdout. Overrides `reporters` and `outputDir` in `hitspec.yaml`		`HITSPEC_OUTPUT_FILE`

Execution Flags

Flag	Short	Description	Default	Env Var
`--bail`		Stop on first failure	`false`	`HITSPEC_BAIL`
`--timeout`		Request timeout (e.g., `30s`, `1m`, `500ms`)	`30s`	`HITSPEC_TIMEOUT`
`--dry-run`		Parse each file and list the requests that would run (method, resolved URL, tags, dependencies, skip reasons) without sending anything (see Dry Run)	`false`
`--parallel`	`-p`	Run independent requests in parallel	`false`	`HITSPEC_PARALLEL`
`--concurrency`		Max concurrent requests when running in parallel	`5`	`HITSPEC_CONCURRENCY`
`--watch`	`-w`	Watch files for changes and re-run tests	`false`

Network Flags

Flag	Short	Description	Default	Env Var
`--proxy`		Proxy URL for HTTP requests		`HITSPEC_PROXY`
`--insecure`	`-k`	Disable SSL certificate validation	`false`	`HITSPEC_INSECURE`
`--cacert`		PEM CA bundle to trust in addition to the system roots		`HITSPEC_CACERT`
`--cert`		PEM client certificate for mutual TLS; needs `--key`		`HITSPEC_CERT`
`--key`		PEM private key for `--cert`		`HITSPEC_KEY`
`--http1.1`		Do not negotiate HTTP/2	`false`	`HITSPEC_HTTP1`
`--cookies`		Keep a cookie jar for the run: `Set-Cookie` from one response is sent on later requests	`false`	`HITSPEC_COOKIES`
`--max-response-bytes`		Largest response body to read, in bytes; `-1` for no limit	`104857600`	`HITSPEC_MAX_RESPONSE_BYTES`
`--redirect-forward-headers`		Keep your request headers on redirects to another origin	`false`	`HITSPEC_REDIRECT_FORWARD_HEADERS`

A CA, certificate or key file that is missing or not valid PEM, and a malformed --proxy URL, exit with code 3 before any request is sent. Each of these also has a hitspec.yaml key; see Configuration and TLS, cookies and HTTP options.

History Flags

Every run is recorded to a local history database (also browsable in studio’s History screen).

Flag	Description	Default	Env Var
`--history-db`	Path to the run-history database	`~/.hitspec/history.db`	`HITSPEC_HISTORY_DB`
`--no-history`	Disable run-history recording for this run	`false`	`HITSPEC_NO_HISTORY`

Snapshot Flags

Flag	Description	Default
`--update-snapshots`	Update snapshot files instead of comparing against them	`false`

Security Flags

Flag	Description	Default
`--allow-shell`	Allow shell command execution (`>>>shell` blocks and hooks)	`false`
`--allow-db`	Allow database assertions (`>>>db` blocks)	`false`

Coverage Flags

Flag	Description	Default
`--coverage`	Generate API coverage report against OpenAPI spec	`false`
`--openapi`	Path to OpenAPI spec file for coverage analysis

Shell and database blocks are disabled by default for security. You must explicitly opt in with --allow-shell or --allow-db when your test files use these features.

Stress Testing Flags

Flag	Short	Description	Default
`--stress`		Enable stress testing mode	`false`
`--duration`	`-d`	Stress test duration (e.g., `30s`, `5m`, `1h`)	`30s`
`--rate`	`-r`	Target requests per second	`10`
`--vus`		Number of virtual users (alternative to `--rate`)	`0`
`--max-vus`		Maximum concurrent requests	`100`
`--think-time`		Think time between requests per virtual user	`0s`
`--ramp-up`		Ramp-up time to reach target rate/VUs	`0s`
`--threshold`		Pass/fail thresholds (e.g., `"p95<200ms,errors<0.1%"`). Metrics: `p50`, `p95`, `p99`, `max`, `errors` (transport errors and non-2xx), `assertions` (assertion failure share), `rps`
`--profile`		Load a stress profile from config file
`--no-progress`		Disable real-time progress display	`false`
`--stress-json`		Output stress results as JSON	`false`

Metrics Flags

Flag	Description	Default	Env Var
`--metrics`	Export format: `prometheus`, `datadog`, `json`. Only applies with `--stress`; without it a warning is printed and nothing is exported		`HITSPEC_METRICS`
`--metrics-port`	Port for Prometheus metrics HTTP endpoint	`9090`	`HITSPEC_METRICS_PORT`
`--metrics-host`	Interface the Prometheus endpoint binds; `0.0.0.0` exposes it to the network	`127.0.0.1`	`HITSPEC_METRICS_HOST`
`--metrics-file`	Output file for JSON metrics		`HITSPEC_METRICS_FILE`
`--datadog-api-key`	DataDog API key		`DD_API_KEY`
`--datadog-site`	DataDog site	`datadoghq.com`	`DD_SITE`
`--datadog-tags`	Comma-separated DataDog tags		`DD_TAGS`

Notification Flags

Flag	Description	Default	Env Var
`--notify`	Notification service: `slack`, `teams`		`HITSPEC_NOTIFY`
`--notify-on`	When to notify: `always`, `failure`, `success`, `recovery`	`failure`	`HITSPEC_NOTIFY_ON`
`--slack-webhook`	Slack webhook URL		`SLACK_WEBHOOK`
`--slack-channel`	Slack channel override		`SLACK_CHANNEL`
`--teams-webhook`	Microsoft Teams webhook URL		`TEAMS_WEBHOOK`

Examples

Basic Usage

hitspec run tests/api.http

hitspec run tests/

hitspec run tests/ --env staging

hitspec run tests/ --name "Login"

hitspec run tests/ --tags smoke

Filtering

# Run only smoke-tagged tests
hitspec run tests/ --tags smoke

# Multiple tags (OR logic)
hitspec run tests/ --tags smoke,critical

# Filter by name pattern (glob matching)
hitspec run tests/ --name "User*"
hitspec run tests/ --name "*Profile"

# Combine filters
hitspec run tests/ --tags smoke --name "*Auth*"

If the filters select no request in any of the files (for example a typo such as --tags smok), hitspec prints no requests matched --tags "smok" to stderr and exits with code 64. A filter only needs to match in one of the files of the run. Requests skipped on purpose with @skip still count as matches. When a selected request has @depends, the requests it depends on are run too (transitively) even if the filters would exclude them, and they are reported like any other request. A dependency that fails still causes its dependents to be skipped.

Quiet Mode

--quiet keeps stdout empty, but it never hides failures:

With --output-file, the formatted report is still written to the file.
When anything fails, one line per failed request is written to stderr with the request name and the first failing assertion or error.
Exit codes are unchanged.

hitspec run tests/ --quiet --output junit --output-file results.xml

Files That Cannot Be Loaded

A file with a syntax error, a duplicate @name, or a circular @depends does not stop the run. The remaining files still run, the error is written to stderr (for example 1 file failed to parse), and the run exits with code 2. With --output json, junit, tap or html, the broken file also appears in the report as an error entry.

Parallel Execution

# Run independent requests in parallel
hitspec run tests/ --parallel

# Set concurrency limit
hitspec run tests/ --parallel --concurrency 10

Requests with dependencies (@depends) always run sequentially. Only independent requests run in parallel. Captured variables are not shared between parallel requests.

Watch Mode

# Watch files and re-run on changes
hitspec run tests/ --watch

# Combine with tags for focused development
hitspec run tests/ --watch --tags dev

--watch re-runs when a test file changes, including editors that save by renaming a temp file over it, and when hitspec.yaml, --config or the env file changes. The settings are reloaded before the next pass, and --output-file is rewritten each time. node_modules, vendor and .git are not watched. With --cookies, the cookie jar is kept across re-runs.

Inputs

hitspec run - reads one document from stdin. Relative paths in it resolve against the working directory. It cannot be combined with other files, --watch or --stress; --dry-run works with it.

hitspec run - < api.http

Quote glob patterns so the shell does not expand them: hitspec run 'tests/**/*.http'. ** matches any depth. Directories are searched recursively, skipping .git, node_modules and vendor unless you name one of them explicitly. A file given more than once runs once. A pattern or path that matches no .http or .hitspec file is an error (exit code 1); so is empty stdin. Combining - with other files, --watch or --stress exits with code 64. Ctrl+C (or SIGTERM) stops the run: hitspec reports the requests that finished, marks the rest as cancelled, writes --output-file, and exits with code 130. A second Ctrl+C exits immediately.

Verbose Output

-v can be repeated; each level adds detail for every request, not only failures.

Flag	Output
(none)	One line per request. A failed request also shows the request line, the response status line with its duration, and a capped body excerpt.
`-v`	The request line and response status of every request, plus captures, SSE events and structured diffs. Also prints the `hitspec.yaml` in use (`config: <path>`) on stderr.
`-vv`	Adds request and response headers. Credentials (`Authorization`, `Cookie`, `Set-Cookie`, anything with `api-key`, `token`, `secret` or `password` in its name) print as `[REDACTED]`.
`-vvv`	Adds the full request and response bodies, uncapped.

Warnings (a capture that matched nothing, a {{reference}} sent unresolved) print in yellow under the request at every level, and are also written to stderr. They never change the exit code.

Dry Run

--dry-run parses each file and prints what would run, in execution order, without sending anything or touching the history database.

Would run: api.http (2 to run, 1 skipped)
  1.  login  POST https://api.example.com/auth/login?v=2
        tags: smoke, auth
  -   legacy  GET https://api.example.com/legacy
        skipped: down for maintenance
  2.  profile  GET https://api.example.com/me?token={{login.token}}
        tags: auth
        depends: login

Environment and file variables are resolved in the URL. References to captured values ({{login.token}}) are left as written. Requests that would not run are marked - with the reason: the @skip text, filtered out, condition not met, or dependency will not run. An @if that depends on a captured value is listed with a note, because only a real run can decide it. --name and --tags apply as in a real run. --dry-run cannot be combined with --stress (usage error, exit 64; nothing is sent). With --dry-run, -o and --output-file are ignored: the plan is always text (a note on stderr says so) and the output file is not created. Exit codes: 0 on success, 2 if a file cannot be loaded (syntax error, duplicate @name, @depends cycle), 64 if the filters match nothing.

Output Formats

hitspec run tests/

hitspec run tests/ --output json

hitspec run tests/ --output junit --output-file results.xml

hitspec run tests/ --output tap

hitspec run tests/ --output html --output-file report.html

Stress Testing

hitspec run api.http --stress --duration 1m --rate 100

hitspec run api.http --stress --vus 50 --think-time 1s

hitspec run api.http --stress -d 1m -r 100 --threshold "p95<200ms,errors<0.1%"

hitspec run api.http --stress --profile load --env staging

CI/CD Integration

# GitHub Actions example
hitspec run tests/ \
  --env staging \
  --output junit \
  --output-file test-results.xml \
  --bail

# With notifications on failure
hitspec run tests/ \
  --env staging \
  --notify slack \
  --slack-webhook "$SLACK_WEBHOOK" \
  --notify-on failure

Snapshot Testing

# First run creates snapshots in __snapshots__/
hitspec run tests/

# Update snapshots when expected changes occur
hitspec run tests/ --update-snapshots

Security Flags

# Allow shell blocks and database assertions
hitspec run tests/ --allow-shell --allow-db

# Only allow shell execution
hitspec run tests/ --allow-shell

Exit Codes

Code	Constant	Description
`0`	`ExitSuccess`	All tests passed
`1`	`ExitTestFailure`	One or more tests failed
`2`	`ExitParseError`	A file could not be loaded (invalid syntax, duplicate `@name`, `@depends` cycle)
`3`	`ExitConfigError`	Configuration error (a `hitspec.yaml` that cannot be parsed, an `--env-file` that does not exist, a missing or invalid `--cacert`, `--cert`, `--key` or `--proxy`)
`4`	`ExitNetworkError`	A request got no response because the connection failed (refused, unreachable, DNS, TLS, reset before a response, timeout before connecting, unreachable OAuth2 token endpoint). A timeout after connecting is a failure (`1`)
`64`	`ExitUsageError`	Usage error (unknown flag, bad flag value, missing argument, `-` combined with other files, `--dry-run` with `--stress`), or `--name`/`--tags` matched no request
`130`	`ExitInterrupted`	Interrupted (Ctrl+C or SIGTERM): partial results printed, `--output-file` written

When several apply: 130, then 2, then 4, then 1, then 64. See Exit Codes.

Environment Variables

All flags that support environment variables are listed in the flag tables above. Environment variables are read at startup and can be overridden by explicit flags. Common variables:

export HITSPEC_ENV=staging
export HITSPEC_TIMEOUT=60s
export HITSPEC_OUTPUT=json
export HITSPEC_BAIL=true
export HITSPEC_PARALLEL=true
export HITSPEC_CONCURRENCY=10