snouty

snouty

A CLI for the Antithesis API. See the webhook documentation for details on available endpoints and parameters.

Usage

Snouty provides the following subcommands. Invoke snouty <command> --help to find out more.

• snouty login: sign in and store your tenant, repository, and credentials.
• snouty launch: push images and kick off an Antithesis run.
• snouty runs: list and inspect Antithesis test runs and their results.
  • snouty runs list: list runs, with status/launcher/date filters.
  • snouty runs show <run_id>: show details for a single run.
  • snouty runs wait [--until ready|complete] <run_id>: poll a run until it is ready to use or complete.
  • snouty runs cancel <run_id>: cancel a run that is starting or in progress.
  • snouty runs properties <run_id>: list property (assertion) results.
  • snouty runs build-logs <run_id>: stream a run's build logs.
  • snouty runs logs <run_id> <hash> [vtime]: stream a run's logs along one branch.
  • snouty runs events <run_id> -m <needle>: search events in a run.
  • snouty runs search <run_id> <query>: run an event-set DSL query against a run's events.
  • snouty runs exec <run_id> <hash> <vtime> [script]: run a bash script at a given moment in a run that is in progress (a test run or a debugging session). Needs tenant release 64.0 or newer.
• snouty debug: start a debug session.
• snouty validate: locally run and validate your docker-compose.yaml setup.
• snouty doctor: check your environment is configured correctly.
• snouty docs: search the Antithesis documentation locally.
• snouty docker-credential <action>: the Docker and Podman credential helper for your tenant registry. See Docker credential helper.
• snouty completions <shell>: generate shell completion scripts.
• snouty version: print version and build information.
• snouty update: install the latest version. Set update_channel = "unstable" (or SNOUTY_UPDATE_CHANNEL=unstable) to also consider pre-releases; override the setting for one run with --channel stable|unstable.

Add --json for machine-readable output. See COOKBOOK.md for worked recipes.

Requirements

Commands that work with docker-compose.yaml files (e.g. launch, validate) require:

• Docker Compose v2 — snouty drives either the standalone docker-compose binary or the docker compose CLI plugin (bundled with Docker Desktop/Engine), whichever it finds on your PATH. podman-compose is no longer supported.
  • Linux: Install Docker Compose or check your package manager.
  • macOS: Install Docker Desktop (includes Compose v2) or brew install docker-compose.
• A container engine — Docker or Podman, used to build and push images.

If both engines are installed, Podman is preferred. Override the engine with SNOUTY_CONTAINER_ENGINE=docker or container_engine in a settings file (see below); an explicit DOCKER_HOST in your environment is always respected.

VM-backed and remote container engines

snouty validate bind-mounts a temp directory from this machine into each container. It watches this directory for the setup-complete event. Some container engines run inside a VM or on another machine. If the engine does not share this machine's temp directory, the engine creates the bind source on its own side and reports no error. The directory on this machine stays empty. Validate then fails with timed out waiting for setup-complete event, even though the system under test emits the event.

There are two fixes:

• Share this machine's temp directory with the engine. See the mount documentation for your engine.

• Set SNOUTY_TEMP_DIR to a directory under a path the engine already shares with write access:

  SNOUTY_TEMP_DIR=/path/shared/with/the/vm/snouty snouty validate ./config

  SNOUTY_TEMP_DIR must point to an empty or non-existent directory. This prevents validate from reading events that a previous run left behind. Snouty does not remove the directory after the run, so remove it before the next run.

Install snouty

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/antithesishq/snouty/releases/latest/download/snouty-installer.sh | sh

This also allows you to update via snouty update later on.

Install prebuilt binaries via cargo binstall

cargo binstall snouty

Install snouty from source

cargo install snouty

Download prebuilt binaries

Uninstalling

cargo uninstall snouty || rm -f "$(which snouty)" "$(which snouty-update)" "$(which docker-credential-snouty)"

If you set up shell completions, also remove the snouty line from your shell's startup file.

Configuration

Using the API requires at least a tenant and a credential. snouty launch also needs a repository — the container registry it pushes the config image to. Docs commands need no configuration at all.

The quickest way is snouty login, which asks for each value and stores the result:

snouty login

Settings can also come from environment variables or a TOML settings file. An environment variable always takes precedence.

export ANTITHESIS_TENANT="your-tenant"
export ANTITHESIS_REPOSITORY="us-central1-docker.pkg.dev/your-project/your-repo"
export ANTITHESIS_API_KEY="your-api-key"

Run snouty settings show at any point to see what snouty resolves, and which settings files it reads. Run snouty doctor to check that your environment works.

Settings files

Settings can instead live in a TOML file. Snouty reads two, the first taking precedence:

1. A project settings file — ./.snouty.toml by default. Point elsewhere with the global --settings <path> flag or the SNOUTY_SETTINGS_PATH environment variable.
2. A global settings file — settings.toml under $XDG_CONFIG_HOME/snouty/ (falling back to $HOME/.config/snouty/).

# .snouty.toml
tenant = "your-tenant"
repository = "us-central1-docker.pkg.dev/your-project/your-repo"

A matching environment variable always overrides the file. The supported keys and their environment-variable equivalents are:

A credential is never read from a settings file. snouty login keeps credentials apart from settings — see Authentication.

Run snouty settings show to print the value that snouty resolved for each setting, and the settings files it read.

Trusting a project settings file

snouty uses ./.snouty.toml only after you trust it. Until you trust or deny the file, each command that reads the settings stops with an error. Review the file, then decide:

snouty settings trust   # use ./.snouty.toml while its content stays the same
snouty settings deny    # ignore ./.snouty.toml

Each command also takes the path of a settings file. When a trusted file changes, you must trust it again. snouty keeps the decisions in trust.toml, next to the global settings file.

A file that you name with --settings or SNOUTY_SETTINGS_PATH needs no trust, because you chose it. To use every project settings file without a check, for example in CI, set SNOUTY_SETTINGS_TRUST=all.

Profiles

A settings file can define named profiles for switching between environments. Select one with the global --profile <name> flag or the ANTITHESIS_PROFILE environment variable (the flag wins):

# .snouty.toml
tenant = "default-tenant"
repository = "registry.example.com/default"

[profile.staging]
tenant = "staging-tenant"
repository = "registry.example.com/staging"

snouty --profile staging runs list

For any one setting, snouty uses the first value it finds, highest precedence first:

1. environment variable
2. the selected profile in the project settings file
3. the selected profile in the global settings file
4. the top-level default in the project settings file
5. the top-level default in the global settings file

Unstable features

When a subcommand or a flag, or the Antithesis API it calls, is still changing shape, snouty can keep it behind a gate, turned on by naming its feature in SNOUTY_UNSTABLE_FEATURES (a comma-separated list). Anything behind this gate can change its behavior, its flags, or its id, or go away, in any release.

An id that snouty does not know, such as the retired runs-exec, has no effect.

MCP server

snouty mcp serves most of snouty's commands to AI agents as Model Context Protocol tools, over the stdio transport. It is an unstable feature: set SNOUTY_UNSTABLE_FEATURES=mcp to turn it on. Run snouty login once before you add the server, which then uses the credential that snouty stores. The agent starts the server itself. For example, in Claude Code:

claude mcp add snouty -e SNOUTY_UNSTABLE_FEATURES=mcp -- snouty mcp

A JSON config for a stdio server looks like this one. The key names can be different in your client, so refer to its documentation:

{
  "mcpServers": {
    "snouty": {
      "command": "snouty",
      "args": ["mcp"],
      "env": { "SNOUTY_UNSTABLE_FEATURES": "mcp" }
    }
  }
}

Run snouty mcp --help to see all tools.

snouty is listed in the MCP Registry as com.antithesis/snouty, so a client that installs from the registry sets the server up for you. The registry checks this line to verify the crate: mcp-name: com.antithesis/snouty.

The server sets no time limit and no output limit on a tool call. The client sets them: when it cancels a call or closes stdin, the server kills the call's command. A command also exits when its server is gone. Up to 8 tool calls run at the same time, and --max-concurrent-calls changes that number.

The server reads settings, profiles, and credentials as the other commands do, so --settings, --profile, --verbose, and the ANTITHESIS_* environment variables apply to every tool call. A client cannot set them.

Debugging the MCP server

1. Set RUST_LOG=debug in the server's environment, and add --verbose to its args. For example: claude mcp add snouty -e SNOUTY_UNSTABLE_FEATURES=mcp -e RUST_LOG=debug -- snouty --verbose mcp.
2. Read the server's stderr in the client. In Claude Code, start claude --debug and use /mcp to see the server's state. The server logs each command line that it runs, as running: snouty --json ….
3. Run the logged command yourself, in a terminal. It prints what the tool call returned. Set RUST_LOG=debug on it too, to see its own debug log: the server does not pass RUST_LOG to its tool calls.

Authentication

Snouty accepts four kinds of credentials: OAuth tokens from a browser sign-in, an API key, a GitHub Actions OIDC token, and a deprecated username and password. On a workstation, run snouty login and let snouty store a credential for you. In CI and in scripts, use environment variables or GitHub Actions OIDC tokens.

Snouty looks for a credential in this order, and uses the first one it finds:

1. ANTITHESIS_API_KEY in the environment.
2. ANTITHESIS_USERNAME and ANTITHESIS_PASSWORD in the environment (deprecated).
3. The credential stored for the selected --profile: the system keychain first, the credentials file second.
4. The credential stored for the default profile: the system keychain first, the credentials file second.
5. A GitHub Actions OIDC token, when the workflow exposes one.

An environment variable always wins over a stored credential. Unset ANTITHESIS_API_KEY when you want snouty to use what snouty login stored.

Run snouty doctor to see which credential snouty resolves, and where it comes from. doctor also warns when more than one source holds a credential, and names the action that hands the run to the next source.

Browser sign-in with snouty login

snouty login asks for your tenant and your repository, then asks how you want to authenticate. It writes the tenant and the repository to the global settings file, and it stores the credential separately.

snouty login
snouty login --tenant "your-tenant" --repository "us-central1-docker.pkg.dev/your-project/your-repo"
snouty login --profile staging

Pick Single sign-on (OAuth) to sign in through your identity provider. Snouty binds a loopback server, opens a browser, and waits up to five minutes for the redirect to come back. It prints the sign-in URL as well, so you can open the URL by hand when it cannot open a browser for you. The exchange uses PKCE, so no shared secret is needed.

Two limits are worth knowing:

• The menu offers single sign-on only when your tenant enables CLI OAuth. Without it, snouty login asks for an API key straight away.
• The browser must run on the same machine as snouty, because the redirect goes to http://localhost:<port>/callback. On a headless machine or a remote VM, either forward that port to your workstation, or use another authentication method.

Where stored credentials live

On macOS, snouty stores the credential in the keychain, under the service name snouty. The entry is named _default_, or profile_<name> for a named profile. Set SNOUTY_DISABLE_KEYCHAIN_CREDENTIAL_STORAGE=1 to use the credentials file instead.

On every other platform, snouty writes credentials.toml next to the global settings file, in $XDG_CONFIG_HOME/snouty/ (falling back to $HOME/.config/snouty/).

API key

An API key works with every command, and needs no browser. Ask Antithesis support for one if you do not have one.

export ANTITHESIS_API_KEY="your-api-key"

snouty login also stores an API key for you, which keeps the key out of your shell history and out of your environment.

GitHub Actions OIDC

In a GitHub Actions workflow, snouty authenticates with the workflow's own OIDC token, so you store no secret. Give the job permission to mint the token:

permissions:
  id-token: write
  contents: read

[!IMPORTANT] Your Antithesis tenant must trust GitHub Actions OIDC tokens from your repository before this works. Ask Antithesis support to configure it.

Credential injection by an HTTPS proxy

Some VM and development platforms hold your credentials for you, and inject them into outbound requests. The platform gives you a hostname that stands in for https://<tenant>.antithesis.com. That hostname terminates TLS, replaces the Authorization header with the real credential, and forwards the request. Your machine never holds the secret. Replit and exe.dev work this way; check your platform's documentation for the hostname it gives you.

Point snouty at that hostname, and give it a placeholder API key:

export ANTITHESIS_BASE_URL="https://antithesis.int.example.com"
export ANTITHESIS_API_KEY="replaced-by-proxy"

Three things to know:

• ANTITHESIS_BASE_URL replaces the URL that snouty derives from the tenant, so every API request goes to the proxy instead. Snouty takes the value as given, and only trims a trailing / or /api/v1.
• Snouty still needs a credential, or it stops before it sends a request. Snouty never inspects the value, so any non-empty string works. Use an obvious placeholder such as replaced-by-proxy, so a reader sees that the real secret is elsewhere. An empty value counts as unset, and does not work.
• Keep ANTITHESIS_TENANT set. Only the derived base URL uses it, and ANTITHESIS_BASE_URL replaces that, but snouty doctor reports a missing tenant as a failure.

snouty doctor confirms the whole setup: it reports the API key as provided, and it contacts the API through the proxy to report the API and tenant versions.

ANTITHESIS_EXTRA_HEADERS adds headers to every API request, as one Name: value pair per line. Use it when the platform expects a header of its own.

export ANTITHESIS_EXTRA_HEADERS="X-Proxy-Token: abc123"

Docker credential helper

docker-credential-snouty gives Docker and Podman your snouty credentials for your tenant's container registry, registry.<tenant>.antithesis.com.

To set it up, add the registry to credHelpers in ~/.docker/config.json for Docker, or in ~/.config/containers/auth.json for Podman:

{
  "credHelpers": {
    "registry.<tenant>.antithesis.com": "snouty"
  }
}

The helper uses the same settings as snouty in the directory where Docker runs it, including ./.snouty.toml. With --profile or ANTITHESIS_PROFILE, the helper uses that profile. Otherwise, it uses the first profile whose repository is on registry.<tenant>.antithesis.com.

The shell script installer and the Nix package install docker-credential-snouty, an alias of snouty. For another install method, make the alias yourself, in a directory on your PATH:

ln -s "$(command -v snouty)" ~/.local/bin/docker-credential-snouty

Then docker push, docker pull, podman push and podman pull automatically use your snouty credentials for the Antithesis docker registry.

snouty launch --config does not need the helper. When the repository is on the tenant registry, snouty gives your credential to Docker or Podman when it pushes the images of the launch. For Docker, this needs Docker 28.3.0 or later. With an older Docker, configure the helper as shown above. For Podman, snouty gives a temporary auth file, which holds no secret, that sends Podman to docker-credential-snouty, and links that helper to itself in its config directory ($XDG_CONFIG_HOME/snouty or ~/.config/snouty). A username and password does not work with the registry, so with it, Docker or Podman pushes with its own credentials.

Username and password (deprecated)

Username and password authentication is deprecated. It works with snouty launch and snouty debug only, and both print a warning that points to snouty login. Every other command that talks to the API refuses it. Use snouty login or an API key instead.

snouty login does not set up a username and password. Set ANTITHESIS_USERNAME and ANTITHESIS_PASSWORD instead. A username and password that an older snouty stored in the credentials file still works.

Running in CI

snouty launch runs in any CI system. In every CI system it records the checked-out commit in run metadata. It also records the branch, when HEAD is on a branch, and the repository and a commit link, when the origin remote is on github.com. In GitHub Actions, it records more: see GitHub Actions.

Each CI job needs these environment variables:

• ANTITHESIS_TENANT: your tenant.
• ANTITHESIS_REPOSITORY: the container registry for your images, with --config. On your tenant registry, registry.<tenant>.antithesis.com, snouty pushes with its own credential. That needs Docker 28.3.0 or later, or the Docker credential helper. For any other registry, log in to it in the job before the launch.
• ANTITHESIS_API_KEY: an API key, stored as a secret. GitHub Actions can use OIDC instead.

snouty does not choose a --source for you. A run without --source is ephemeral: its results do not go into the property history of any source. To record history for a branch, pass --source only in the jobs that build that branch, such as pushes to main and nightly schedules. Do not pass a pull request's branch name as the source: a pull request from a fork can use any branch name, such as main.

--config builds the config image and pushes the images, so the job needs Docker or Podman.

GitHub Actions

snouty launch can replace the Antithesis Trigger Action. In GitHub Actions, it records the same metadata as the action: the repository, the branch, the commit, the pull request (vcs.pr_id, vcs.pr_link, vcs.pr_owner and vcs.pr_title), the user who started the workflow (run.creator_name), and the cron schedule of a scheduled workflow (run.cron_schedule). It records run.caller_type as snouty. On a pull request, it records the head commit of the pull request, not the merge commit that the workflow checks out. When the job checks out a different commit, for example another ref or another repository, the launch reads the git checkout instead.

This workflow starts a run for each push to main and each pull request from a branch of the repository. Only a push to main records property history. A pull request from a fork, or from Dependabot, gets no OIDC token and no secrets, so the job skips it:

name: Antithesis
on:
  push:
    branches: [main]
  pull_request:

jobs:
  antithesis:
    if: >-
      github.event_name == 'push' ||
      (github.event.pull_request.head.repo.full_name == github.repository &&
       github.actor != 'dependabot[bot]')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
      - name: Install snouty
        run: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/antithesishq/snouty/releases/latest/download/snouty-installer.sh | sh
      # The runner's Docker is older than 28.3.0, so it needs the credential
      # helper for the tenant registry.
      - name: Use snouty for the tenant registry
        run: |
          mkdir -p ~/.docker
          [ -f ~/.docker/config.json ] || echo '{}' > ~/.docker/config.json
          jq '.credHelpers["registry.my-tenant.antithesis.com"] = "snouty"' ~/.docker/config.json > "$RUNNER_TEMP/config.json"
          mv "$RUNNER_TEMP/config.json" ~/.docker/config.json
      - name: Launch an Antithesis run
        env:
          ANTITHESIS_TENANT: my-tenant
          ANTITHESIS_REPOSITORY: registry.my-tenant.antithesis.com/my-project
          ANTITHESIS_GITHUB_TOKEN: ${{ secrets.GH_PAT }}
          # The runner has Podman too, and snouty prefers it by default.
          SNOUTY_CONTAINER_ENGINE: docker
          SOURCE: ${{ github.event_name == 'push' && github.ref_name || '' }}
        run: |
          snouty launch --launcher basic_test --config ./antithesis \
            --test-name smoke --duration 30m ${SOURCE:+--source "$SOURCE"}

The job authenticates with GitHub Actions OIDC. To use an API key instead, remove id-token: write and set ANTITHESIS_API_KEY: ${{ secrets.ANTITHESIS_API_KEY }}.

When ANTITHESIS_GITHUB_TOKEN is set, the launch sets the continuous-testing/antithesis commit status of the commit to pending, and Antithesis sets the result when the run ends. With --test-name, the status is continuous-testing/antithesis (<test-name>), so two tests on one commit get two statuses. Antithesis uses the token after the job ends, so secrets.GITHUB_TOKEN does not work. Use a fine-grained personal access token for the repository, with read access to metadata and read and write access to commit statuses, and store it as the GH_PAT secret.

A --param replaces the detected parameter with the same key. --no-vcs turns off the vcs.* detection, but not the commit status.

Each input of the trigger action has a snouty equivalent:

The action always sends the branch as antithesis.source. With snouty, pass --source yourself, as in the workflow above.

GitLab CI

GitLab CI checks out a detached HEAD, so the launch records the commit but no branch. This job records history for the default branch only. Store ANTITHESIS_API_KEY as a masked CI/CD variable:

antithesis:
  image: docker:latest
  services: [docker:dind]
  variables:
    ANTITHESIS_TENANT: my-tenant
    ANTITHESIS_REPOSITORY: registry.my-tenant.antithesis.com/my-project
  before_script:
    - apk add --no-cache curl git xz
    - curl --proto '=https' --tlsv1.2 -LsSf https://github.com/antithesishq/snouty/releases/latest/download/snouty-installer.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - if [ "$CI_COMMIT_BRANCH" = "$CI_DEFAULT_BRANCH" ]; then SOURCE="$CI_COMMIT_BRANCH"; fi
    - snouty launch --launcher basic_test --config ./antithesis --duration 30m ${SOURCE:+--source "$SOURCE"}

Buildkite

Buildkite checks out a detached HEAD, so the launch records the commit but no branch. For a repository on github.com, it also records the repository and a commit link. Give the agent ANTITHESIS_API_KEY from your secrets store. $$ keeps Buildkite from replacing a variable when it uploads the pipeline:

steps:
  - label: Antithesis
    env:
      ANTITHESIS_TENANT: my-tenant
      ANTITHESIS_REPOSITORY: registry.my-tenant.antithesis.com/my-project
    command: |
      curl --proto '=https' --tlsv1.2 -LsSf https://github.com/antithesishq/snouty/releases/latest/download/snouty-installer.sh | sh
      export PATH="$$HOME/.local/bin:$$PATH"
      if [ "$$BUILDKITE_BRANCH" = "$$BUILDKITE_PIPELINE_DEFAULT_BRANCH" ] && [ "$$BUILDKITE_PULL_REQUEST" = "false" ]; then SOURCE="$$BUILDKITE_BRANCH"; fi
      snouty launch --launcher basic_test --config ./antithesis --duration 30m $${SOURCE:+--source "$$SOURCE"}

CircleCI

CircleCI checks out the branch of a branch build, so the launch records the commit and the branch. For a repository on github.com, it also records the repository and a commit link. Store ANTITHESIS_API_KEY in a context or a project environment variable:

version: 2.1
jobs:
  antithesis:
    machine:
      image: ubuntu-2404:current
    environment:
      ANTITHESIS_TENANT: my-tenant
      ANTITHESIS_REPOSITORY: registry.my-tenant.antithesis.com/my-project
    steps:
      - checkout
      - run: |
          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/antithesishq/snouty/releases/latest/download/snouty-installer.sh | sh
          export PATH="$HOME/.local/bin:$PATH"
          if [ "$CIRCLE_BRANCH" = main ] && [ -z "$CIRCLE_PULL_REQUEST" ]; then SOURCE=main; fi
          snouty launch --launcher basic_test --config ./antithesis --duration 30m ${SOURCE:+--source "$SOURCE"}
workflows:
  antithesis:
    jobs: [antithesis]

Commit status from another CI system

Only GitHub Actions sends the GitHub callback params for you. For a repository on GitHub that another CI system builds, pass them yourself. Then the launch also sets the commit status to pending:

snouty launch --launcher basic_test --config ./antithesis \
  --param "antithesis.integrations.github.callback_url=https://api.github.com/repos/OWNER/REPO/statuses/$COMMIT" \
  --param "antithesis.integrations.github.token=$GITHUB_PAT"

Shell Completions

Snouty supports tab completions for bash, zsh, fish, elvish, and PowerShell. Have your shell generate them at startup, as below. A completion script saved to a file describes the snouty that wrote it, and goes stale when snouty update installs a new version. Open a new shell after each update to load the new completions.

Bash

# Add to ~/.bashrc
eval "$(snouty completions bash)"

Zsh

# Add to ~/.zshrc, after compinit
autoload -Uz compinit
compinit
source <(snouty completions zsh)

Fish

# Put this line in ~/.config/fish/completions/snouty.fish
snouty completions fish | source

Elvish

# Add to ~/.config/elvish/rc.elv
if (has-external snouty) { eval (snouty completions elvish | slurp) }

PowerShell

# Add to $PROFILE
snouty completions powershell | Out-String | Invoke-Expression

Credits

This project was originally developed by orbitinghail for use by Graft. It was donated to Antithesis for the benefit of everyone on Feb 27, 2026.