Getting Started

Install the CLI

curl -fsSL https://app.gaffer.sh/install.sh | sh

This installs the gaffer binary to ~/.local/bin. The script detects your OS and architecture automatically.

Initialize your project

Run gaffer init in your project root:

gaffer init

The setup wizard will:

1. Detect your test frameworks — Vitest, Playwright, Jest, pytest, Go, RSpec
2. Show reporter setup instructions — so your framework outputs a format Gaffer can parse (JUnit XML, CTRF, or native)
3. Authenticate via browser (optional) — creates an API token for syncing results to the dashboard
4. Write .gaffer/config.toml — stores your token and report patterns
5. Add .gaffer/ to .gitignore

Caution

Keep your API token secure. Don’t commit .gaffer/config.toml to version control. In CI, use the GAFFER_TOKEN environment variable instead.

Run your tests

Wrap your existing test command with gaffer test:

gaffer test -- npm test

Gaffer runs your command, parses the results, and prints an enriched summary:

gaffer  40 passed  2 failed  3 skipped  12.4s
Health: 87 (good) ^  Slow: p95 245.3ms
Flaky: 2 tests
   src/auth.test.ts > login — 40% flip rate (4/10 runs)
   src/api.test.ts > timeout handler — 20% flip rate (2/10 runs)
Coverage: 78.5% lines (1234/1572)
Synced: 1 run uploaded

Works with any test command — pytest, go test ./..., cargo test, pnpm test, etc.

Sync to the dashboard

If you authenticated during gaffer init, results sync automatically after each run. If you skipped that step:

1. Sign up and create a project
2. Copy the API token from your project settings
3. Add it to your config:

gaffer init  # re-run to authenticate via browser

Or set the token directly:

.gaffer/config.toml

[project]
token = "gaf_..."

Once synced, your team can view test history, trends, and analytics in the dashboard.

Add to CI

Install the CLI and set GAFFER_TOKEN as a secret. Example for GitHub Actions (see the full GitHub Actions guide for more options):

- name: Install Gaffer CLI
  run: curl -fsSL https://app.gaffer.sh/install.sh | sh

- name: Run tests
  run: gaffer test -- npm test
  env:
    GAFFER_TOKEN: ${{ secrets.GAFFER_TOKEN }}

Next steps

CLI Reference All commands, flags, and configuration options.

MCP Server Give AI coding agents structured access to your test data.

CI Providers Setup guides for GitHub Actions, GitLab CI, CircleCI, and more.

Upload API Upload reports directly via HTTP without the CLI.