tusk-drift-cli

Tusk Drift is an API test record/replay system that lets you run realistic tests generated from real traffic. This CLI orchestrates local and CI test runs, coordinating with a Tusk Drift SDK and Tusk Drift Cloud.

SDKs:

• Node.js
• ...more to come!

Features

• Replay recorded traces against your service under test
• Deterministic outbound I/O via local mock server
• JSON response comparison with dynamic field rules (UUIDs, timestamps, dates, etc.)
• Tusk Drift Cloud: fetch and replay tests stored with Tusk, and upload test results for intelligent classification of regressions in CI/CD checks

Install

Quick install (recommended)

Linux/macOS:

# Install latest version
curl -fsSL https://raw.githubusercontent.com/Use-Tusk/tusk-drift-cli/main/install.sh | sh

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/Use-Tusk/tusk-drift-cli/main/install.sh | sh -s -- v1.2.3

Homebrew:

Coming soon.

Windows:

Download the latest release from GitHub Releases:

1. Download tusk-drift-cli_*_Windows_x86_64.zip
2. Extract the ZIP file
3. Move tusk.exe to a directory in your PATH, or add the extracted directory to your PATH

Manual Download

Download pre-built binaries from GitHub Releases.

Build from source

# Go 1.25+
git clone https://github.com/Use-Tusk/tusk-drift-cli.git
cd tusk-drift-cli
make deps
make build

tusk --help

Quick start

Initialize a service:

cd path/to/your/service
tusk init

An onboarding wizard will guide you to create your .tusk/config.yaml config file. You can also create the .tusk directory and config file manually in your root directory of your service. See configuration docs.

You will need to record traces for your service. See your respective SDK's guide for more details. Once you have traces recorded, you can replay them with the tusk run command.

Local traces (default):

# Run all tests from local traces
tusk run

# Or specify source
tusk run --trace-dir .tusk/traces
tusk run --trace-file path/to/trace.jsonl
tusk run --trace-id <traceId>

# Common flags
tusk run --filter '^/api/users' --concurrency 10 --enable-service-logs
tusk run --save-results --results-dir .tusk/results

Cloud mode:

# Provide a service ID and API URL in config (see below)
# Auth via API key (recommended) or device login
export TUSK_API_KEY=your-key

# Or, device login
tusk login

# Run against Tusk Drift Cloud
tusk run --cloud
tusk run --cloud --trace-test-id <id>           # single test from backend
tusk run --cloud --all-cloud-trace-tests        # run all tests for service

Usage

List traces:

# Local traces
tusk list
tusk list --trace-dir .tusk/traces

# With Tusk Drift Cloud
tusk list --cloud

Interactive TUI (default when attached to a terminal):

tusk run

The TUI is best viewed in a window size of at least 150 x 40.

Run headless mode with JSON output for a single test:

tusk run --trace-id <id> --print --output-format=json

How this program uses your .tusk directory:

• Recordings of your app's traffic will be stored in .tusk/traces by default. Specify traces.dir in your .tusk/config.yaml to override.
• If --save-results is provided, results will be stored in .tusk/results by default. Specify results.dir in your .tusk/config.yaml to override.
• If --enable-service-logs or --debug is used, trace replay service logs will be stored in .tusk/logs.

We recommend adding to your .gitignore:

• .tusk/results
• .tusk/logs
• .tusk/traces (if you primarily intend to use Tusk Drift Cloud)

Resources

• Architecture overview
• Configuration

Community

Join our open source community on Slack.

Development

See CONTRIBUTING.md.

License

See LICENSE.