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 formula.

brew install tales-testing/tap/tales

To upgrade later:

brew update
brew upgrade tales

The tap installs the same release archive published on GitHub, so what you get locally is byte-identical to what runs in CI.

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

Homebrew tap layout

If you maintain your own fork, the formula lives at Formula/tales.rb in tales-testing/homebrew-tap:

class Tales < Formula
  desc "Declarative integration and end-to-end testing tool"
  homepage "https://taleslabs.org/"
  license "MIT"
  version "0.1.0"

  on_macos do
    on_arm do
      url "https://github.com/tales-testing/tales/releases/download/v#{version}/tales_#{version}_darwin_arm64.tar.gz"
      sha256 "REPLACE_WITH_ACTUAL_SHA256"
    end
    on_intel do
      url "https://github.com/tales-testing/tales/releases/download/v#{version}/tales_#{version}_darwin_x86_64.tar.gz"
      sha256 "REPLACE_WITH_ACTUAL_SHA256"
    end
  end

  on_linux do
    on_arm do
      url "https://github.com/tales-testing/tales/releases/download/v#{version}/tales_#{version}_linux_arm64.tar.gz"
      sha256 "REPLACE_WITH_ACTUAL_SHA256"
    end
    on_intel do
      url "https://github.com/tales-testing/tales/releases/download/v#{version}/tales_#{version}_linux_x86_64.tar.gz"
      sha256 "REPLACE_WITH_ACTUAL_SHA256"
    end
  end

  def install
    bin.install "tales"
  end

  test do
    assert_match "tales", shell_output("#{bin}/tales --version")
  end
end

Bump the version field and refresh each sha256 (from the checksums.txt artifact published next to the release) whenever a new tag lands on tales-testing/tales. There is no automation pushing this update for now; the official tap is maintained by hand on each release.

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.