snouty

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

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

File	Platform	Checksum
snouty-aarch64-apple-darwin.tar.xz	Apple Silicon macOS	checksum
snouty-aarch64-unknown-linux-musl.tar.xz	ARM64 Linux	checksum
snouty-x86_64-unknown-linux-musl.tar.xz	x64 Linux	checksum

Uninstalling

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

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.

Configuration

Using the API requires at least a tenant and a repository. These (and other settings) can be supplied via environment variables or a TOML settings file; environment variables always take precedence. Docs commands require no configuration at the moment.

The quickest way is environment variables:

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

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:

Settings key	Environment variable
tenant	ANTITHESIS_TENANT
repository	ANTITHESIS_REPOSITORY
base_url	ANTITHESIS_BASE_URL
container_engine	SNOUTY_CONTAINER_ENGINE
update_channel	SNOUTY_UPDATE_CHANNEL

Authentication (below) is read from the environment only, never from a settings file.

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

Authentication

Antithesis supports two forms of authentication, supplied via environment variables only. An API key works with every command and is the recommended option:

export ANTITHESIS_API_KEY="your-api-key"

Username/password authentication is only supported when launching runs (snouty launch and snouty debug). All other commands that talk to the API — such as snouty runs — require an API key.

export ANTITHESIS_USERNAME="your-username"
export ANTITHESIS_PASSWORD="your-password"

If you don't have an API key, ask Antithesis support for one.

Usage

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

• 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 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> <query>: search events in a run.
• 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 (auto-refreshes the local copy over the network; pass --offline to skip).
• 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.

Shell Completions

Snouty supports tab completions for bash, zsh, fish, and elvish.

Bash

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

Zsh

# Add to ~/.zshrc
eval "$(snouty completions zsh)"

Fish

snouty completions fish > ~/.config/fish/completions/snouty.fish

Elvish

snouty completions elvish > ~/.config/elvish/lib/snouty.elv

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.