snouty

snouty

A CLI for the Antithesis API. See the REST API reference for details on available endpoints and parameters.

Usage

Snouty provides the following subcommands. Invoke snouty --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 : show details for a single run.
• snouty runs wait [--until ready|complete] : poll a run until it is ready to use or complete.
• snouty runs cancel : cancel a run that is starting or in progress.
• snouty runs properties : list property (assertion) results.
• snouty runs build-logs : stream a run's build logs.
• snouty runs logs [vtime]: stream a run's logs along one branch.
• snouty runs events -m : search events in a run.
• snouty runs search : run an event-set DSL query against a run's events.
• snouty runs exec [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 : the Docker and Podman credential helper for your tenant registry. See Docker credential helper.
• snouty completions : 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 prebuilt binaries via npm

npm install -g snouty

The package downloads the prebuilt binary for your platform from the GitHub Release on its first run, and installs the Docker credential helper.

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

| teams | launch --max-compute-hours, launch --setup-timeout and debug --duration. They need tenant version 66 o