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:

• 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

Linux/macOS:

Install the latest version:

curl -fsSL https://cli.usetusk.ai/install.sh | sh

To install a specific version:

curl -fsSL https://cli.usetusk.ai/install.sh | sh -s -- v1.2.3

Linux additional dependencies (for replay sandboxing):

• Debian/Ubuntu: sudo apt install bubblewrap socat
• Fedora/RHEL: sudo dnf install bubblewrap socat
• Arch: sudo pacman -S bubblewrap socat

Without these, sandboxing is disabled and replays run without network isolation. See Architecture - Sandboxing.

Homebrew:

Coming soon.

Windows:

We recommend using WSL for the best experience on Windows. With WSL, you can use the Linux/macOS installation steps above and avoid Windows-specific configuration. For native Windows installation without WSL, expand below to see the steps.

Download pre-built binaries from GitHub Releases.

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

tusk --help

Use our AI agent to automatically set up Tusk Drift for your service:

cd path/to/your/service
export ANTHROPIC_API_KEY=your-api-key
tusk setup

The agent will analyze your codebase, instrument the SDK, create configuration files, and test the setup with recording and replay. Supported languages: Python and Node.js.

Alternatively, use the interactive wizard:

cd path/to/your/service
tusk init

This will guide you to create your .tusk/config.yaml config file. You can also create the .tusk directory and config file manually. 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

You can use Tusk Drift as API tests in your CI/CD pipeline by running your test suite against commits in your pull requests. Tusk Drift Cloud offers storage of these tests alongside an additional layer of intelligence on deviations detected:

• Automatic recording of traces based on live traffic in your environment of choice
• Securely store these traces as test suites
• Analyze deviations (classification of intended vs unintended deviations), root cause of deviations against your code changes, and suggested fixes.

If you used tusk setup, cloud configuration is included. Otherwise, run the cloud onboarding wizard:

For more details, dive into Tusk Drift Cloud docs.

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

# 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

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)

Join our open source community on Slack.

See CONTRIBUTING.md.

See LICENSE.