tarn run
Purpose: Execute test files and produce results.
Syntax: tarn run [PATH] [OPTIONS]
Key options:
| Flag | Description |
|---|---|
[PATH] | Test file or directory to run |
--format <FORMAT> | Output format(s): human, json, junit, tap, html, curl, curl-all, compact, llm, FORMAT=PATH |
--json-mode <MODE> | verbose (default) or compact |
--tag <TAGS> | Filter by tag (comma-separated) |
--select FILE[::TEST[::STEP]] | Select file/test/step (repeatable) |
--var KEY=VALUE | Override env variables (repeatable) |
--env <NAME> | Load tarn.env.{name}.yaml |
--verbose | Print full request/response for every step |
--only-failed | Show only failed tests |
--no-progress | Disable progress output |
--ndjson | Stream NDJSON events to stdout |
--dry-run | Show interpolated requests without sending |
--watch | Re-run on file changes |
--parallel | Run files in parallel |
-j, --jobs <N> | Number of parallel workers |
--insecure | Disable TLS verification |
--http1.1 / --http2 | Force HTTP version |
--proxy <URL> | Proxy URL |
--cacert <FILE> | Custom CA bundle |
--cert <FILE> / --key <FILE> | Client certificates |
--agent | Emit AgentReport JSON for MCP/automation |
Examples:
$ tarn run $ tarn run tests/users.tarn.yaml $ tarn run --format json --json-mode compact $ tarn run --format human --format json=reports/run.json $ tarn run --tag smoke $ tarn run --select tests/users.tarn.yaml::login $ tarn run --ndjson $ tarn run --only-failed $ tarn run --watch $ tarn run --env prod --var base_url=https://api.example.com $ tarn run --parallel -j 4
tarn validate
Purpose: Validate YAML syntax and schema without executing tests.
Syntax: tarn validate [PATH] [OPTIONS]
| Flag | Description |
|---|---|
[PATH] | File or directory to validate |
--format <FORMAT> | human (default) or json |
Examples:
$ tarn validate $ tarn validate tests/ $ tarn validate --format json $ tarn validate tests/users.tarn.yaml
tarn fmt
Purpose: Format test files into canonical YAML.
| Flag | Description |
|---|---|
[PATH] | File or directory to format |
--check | Check without writing (exits 1 on drift) |
Examples:
$ tarn fmt tests/ $ tarn fmt --check tests/ $ tarn fmt tests/users.tarn.yaml
tarn list
Purpose: List all tests without executing.
| Flag | Description |
|---|---|
--tag <TAGS> | Filter by tag |
--file <FILE> | Restrict to single file |
--format <FORMAT> | human (default) or json |
Examples:
$ tarn list $ tarn list --format json $ tarn list --tag smoke $ tarn list --file tests/users.tarn.yaml
tarn init
Purpose: Scaffold a new Tarn project with example files.
Examples:
$ tarn init $ tarn init my-project
tarn env
Purpose: Inspect resolved environment variables.
| Flag | Description |
|---|---|
--json | JSON output |
Examples:
$ tarn env $ tarn env --json
tarn lint
Purpose: Lint test files for reliability smells and correctness errors.
| Flag | Description |
|---|---|
[PATH] | File or directory to lint |
--format <FORMAT> | human (default) or json |
--severity <LEVEL> | error, warning (default), info |
Examples:
$ tarn lint $ tarn lint --format json $ tarn lint --severity error
tarn bench
Purpose: Benchmark a test step with concurrent requests.
| Flag | Description |
|---|---|
PATH | Test file (required) |
-n, --requests <N> | Total requests (default 100) |
-c, --concurrency <N> | Concurrent workers (default 10) |
--step <INDEX> | Step index to benchmark (default 0) |
--ramp-up <DURATION> | Ramp-up duration |
--fail-under-rps <N> | Fail if throughput below N req/s |
--fail-above-p95-ms <N> | Fail if p95 latency above N ms |
Examples:
$ tarn bench tests/endpoint.tarn.yaml -n 1000 -c 20 $ tarn bench tests/endpoint.tarn.yaml --step 0 --format json $ tarn bench tests/endpoint.tarn.yaml --fail-under-rps 500
tarn failures
Purpose: Group failures from a prior run by root cause and suppress cascade noise.
| Flag | Description |
|---|---|
--run <ID> | Run ID (or last/latest/prev) |
--format <FORMAT> | human (default) or json |
Examples:
$ tarn failures $ tarn failures --run last --format json
tarn rerun
Purpose: Rerun only the failing subset of a prior run.
Examples:
$ tarn rerun --failed $ tarn rerun --run last --failed --format json
tarn inspect
Purpose: Inspect a prior run's report at run/file/test/step level.
| Flag | Description |
|---|---|
run_id | Run ID (required positional) |
target | Optional drill-down: FILE, FILE::TEST, FILE::TEST::STEP |
Examples:
$ tarn inspect last $ tarn inspect last tests/users.tarn.yaml::login $ tarn inspect last --format json
tarn diff
Purpose: Compare two runs' summary and failure sets.
Examples:
$ tarn diff last prev $ tarn diff abc123 def456 --format json
tarn report
Purpose: Concise re-render of a prior run's persisted artifacts.
| Flag | Description |
|---|---|
--run <ID> | Run ID |
--format <FORMAT> | concise (default) or json |
tarn pack-context
Purpose: Pack a minimum remediation bundle for AI agents.
| Flag | Description |
|---|---|
--run <ID> | Run ID |
--format <FORMAT> | json (default) or markdown |
tarn impact
Purpose: Map a code change to the Tarn tests most likely affected.
Examples:
$ tarn impact --diff $ tarn impact --files src/api/users.rs $ tarn impact --endpoints "POST:/users"
tarn scaffold
Purpose: Scaffold a minimal .tarn.yaml from OpenAPI specs or curl commands.
| Flag | Description |
|---|---|
--from-openapi <FILE> | OpenAPI 3.x spec path |
--op-id <ID> | OperationId to scaffold |
--from-curl <FILE> | Curl command file |
--method <METHOD> | HTTP method |
--url <URL> | Request URL |
Examples:
$ tarn scaffold --from-openapi spec.yaml --op-id createUser $ tarn scaffold --from-curl curl.txt $ tarn scaffold --method GET --url https://api.example.com/users
tarn completions
Purpose: Generate shell completion scripts.
Examples:
$ tarn completions bash $ tarn completions zsh $ tarn completions fish
tarn update
Purpose: Update Tarn to the latest version.
| Flag | Description |
|---|---|
--check | Check for update without installing |
tarn summary
Purpose: Re-render a prior JSON report in LLM/compact format.
tarn import-hurl
Purpose: Convert common-case .hurl files to Tarn YAML.