Installation

Tales ships as a single static Go binary. Linux and macOS are supported on both amd64 and arm64. There are four installation paths; pick the one that fits where you are running Tales.

Homebrew (macOS / Linux)

The fastest path on a developer machine. The tales-testing/homebrew-tap repository hosts the cask.

brew install --cask tales-testing/tap/tales

To upgrade later:

brew update
brew upgrade --cask tales

The cask installs the same release archive published on GitHub, so what you get locally is byte-identical to what runs in CI. On macOS the cask also runs a postflight hook that strips the com.apple.quarantine attribute from the binary, so the first tales --version does not trip Gatekeeper’s “developer cannot be verified” prompt.

Upgrading from the legacy formula

Releases up to v0.1.0-rc.7 shipped a Homebrew formula at Formula/tales.rb. From v0.1.0 onwards Tales is distributed as a cask at Casks/tales.rb. If you installed the formula before, uninstall it once before switching:

brew uninstall tales 2>/dev/null || true
brew install --cask tales-testing/tap/tales

The transition is one-shot: brew upgrade --cask tales keeps working after that.

GitHub Action (CI)

Use the tales-testing/setup-tales-action GitHub Action to pin and install Tales on a runner.

- name: Install Tales
  uses: tales-testing/setup-tales-action@v1
  with:
    version: latest   # or a pinned tag like v0.1.0

- name: Run scenarios
  run: tales test ./e2e/pass --seed 1234 --parallel 8

The action caches the binary across runs and exposes tales --version to subsequent steps. See CI integration for full workflow recipes.

Pin the version in CI

In production pipelines, prefer a pinned tag (v0.1.0) over latest. A pinned version means a red build is reproducible months later with the exact same binary.

Pre-built binary

Download the release archive for your platform from GitHub Releases and drop it into PATH. The GoReleaser archive name is tales_<version>_<os>_<arch>.tar.gz, so set VERSION to a published tag from the releases page (without the leading v) before running the snippet.

Linux (x86_64)

VERSION=0.1.0   # check the releases page for the latest tag
curl -fsSL -o tales.tar.gz \
  "https://github.com/tales-testing/tales/releases/download/v${VERSION}/tales_${VERSION}_linux_x86_64.tar.gz"
tar -xzf tales.tar.gz
sudo install -m 0755 tales /usr/local/bin/tales
tales --version

Linux (arm64)

VERSION=0.1.0   # check the releases page for the latest tag
curl -fsSL -o tales.tar.gz \
  "https://github.com/tales-testing/tales/releases/download/v${VERSION}/tales_${VERSION}_linux_arm64.tar.gz"
tar -xzf tales.tar.gz
sudo install -m 0755 tales /usr/local/bin/tales
tales --version

macOS

VERSION=0.1.0   # check the releases page for the latest tag
curl -fsSL -o tales.tar.gz \
  "https://github.com/tales-testing/tales/releases/download/v${VERSION}/tales_${VERSION}_darwin_arm64.tar.gz"
tar -xzf tales.tar.gz
sudo install -m 0755 tales /usr/local/bin/tales
# Optional, only needed if Gatekeeper quarantines the archive:
xattr -d com.apple.quarantine tales 2>/dev/null || true
tales --version

From source

Go 1.26+ and a working git are required.

git clone https://github.com/tales-testing/tales
cd tales
make install   # installs to $GOBIN, falls back to $GOPATH/bin

For a one-shot install without a clone:

go install github.com/tales-testing/tales/cmd/tales@latest

Next steps

Your first scenario

Write, validate, and run a complete scenario in five minutes.

CLI essentials

Every flag, every exit code, every environment variable.