Tarn
Guide 01

Get Tarn running in minutes.

Scaffold once, point tarn.env.yaml at a real API, and keep iteration tight with tarn fmt, validate, run, and watch.

Install

$ curl -fsSL https://raw.githubusercontent.com/NazarKalytiuk/tarn/main/install.sh | sh

# or from source
$ cargo install --git https://github.com/NazarKalytiuk/tarn.git --bin tarn
# macOS / Linux
$ curl -fsSL https://raw.githubusercontent.com/NazarKalytiuk/tarn/main/install.sh | sh

# From source with cargo
$ cargo install --git https://github.com/NazarKalytiuk/tarn.git --bin tarn

# Also install companion tools
$ cargo install tarn-mcp
$ cargo install tarn-lsp

Verify installation

$ tarn --version
$ which tarn
$ tarn help

PATH troubleshooting

If tarn: command not found appears after installation:

$ export PATH="$HOME/.cargo/bin:$PATH"
# Add to ~/.zshrc or ~/.bashrc
$ echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc

Quick start

Create tests/health.tarn.yaml:

name: Health check
steps:
  - name: GET /health
    request:
      method: GET
      url: "{{ env.base_url }}/health"
    assert:
      status: 200

Set base_url in tarn.env.yaml:

base_url: "http://localhost:3000"

Run tests

# Run all tests
$ tarn run

# Run specific file
$ tarn run tests/health.tarn.yaml

# Validate before run
$ tarn validate
$ tarn validate --format json

JSON output

$ tarn run --format json
$ tarn run --format json --json-mode compact

Understanding output

A passed test shows a green status; a failed test shows red with details about what went wrong. The JSON format returns structured data including failure_category, assertions.failures, and the full request and response payloads for failed steps, making it easy to integrate with CI pipelines and automated tooling.

Scaffold a project

$ tarn init

Run tarn init to generate the standard project layout including a runnable health check, environment template, and example files. The scaffold keeps the default tests/health.tarn.yaml runnable, and puts heavier auth, polling, multipart, and multi-user examples under examples/ so your first tarn run does not immediately depend on app-specific endpoints.

Core loop

$ tarn fmt tests/ --check
$ tarn validate
$ tarn validate --format json
$ tarn run --format human
$ tarn run --format json --json-mode compact
$ tarn run --ndjson --select tests/smoke.tarn.yaml
$ tarn run --only-failed
$ tarn run --watch

Use tarn validate --format json to get machine-readable parse diagnostics, tarn run --ndjson to stream one event per line (file_started, step_finished, test_finished, file_finished, done), and tarn run --select FILE[::TEST[::STEP]] (repeatable, ANDs with --tag) to scope a single run. tarn run --only-failed replays the last run's failures. tarn env --json dumps the resolved environment for inspection.

Run the local demo path

$ PORT=3000 cargo run -p demo-server &
$ cargo run -p tarn -- run examples/demo-server/hello-world.tarn.yaml

The demo server covers health checks, Unicode JSON, redirects, cookies, form echoing, plain-text responses, HTML error pages, slow responses, and authenticated CRUD.

What to edit first

  • Set base_url in tarn.env.yaml.
  • Run tarn fmt after hand-editing YAML to normalize aliases and field order.
  • Use tarn validate before the first live run if you generated the file with an LLM.
  • Switch to --format json --json-mode compact when the output is for automation, not humans.

Editor intelligence

$ cargo install tarn-lsp

tarn-lsp is a standalone LSP 3.17 language server for .tarn.yaml files. It provides schema-aware diagnostics, hover with inline JSONPath evaluation, nested completion, document symbols, go-to-definition, references, rename, code lens (Run test / Run step), whole-document formatting, and quick-fix code actions backed by the same engine as tarn_fix_plan. Install it once and wire it into any LSP 3.17 client:

  • Claude Code — three-command install via the bundled local marketplace at editors/claude-code/.
  • VS Code — the Tarn extension ships direct providers today and Phase V scaffolding behind tarn.experimentalLspClient.
  • Neovim — vim.lsp.start({ cmd = { "tarn-lsp" }, … }) plus a vim.filetype.add rule.
  • Helix — a [[language]] block in languages.toml.
  • Zed and Emacs (eglot / lsp-mode) — point at tarn-lsp on $PATH.

Full feature list, recipes, and the tarn.evaluateJsonpath command reference live on the tarn-lsp page.

Next steps

Once you’re comfortable with running tests, explore:

  • Writing complex test files with captures and assertions
  • Using environment files for different deployments
  • Setting up CI integration
  • Integrating with MCP for AI-assisted test development