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

Build locally:

# 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

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)

Troubleshooting

• SDK connect failure: ensure your service uses the Tusk Drift SDK and is started by the CLI (so it sees TUSK_MOCK_SOCKET).
• Port in use: the CLI will block if service.port is already taken.
• Readiness: if service.readiness_check.command is omitted, the CLI waits ~10s before replay.
• No mock found: check suite spans availability and matching rules; ensure traces exist for the trace being replayed.
• For Cloud mode, ensure service.id, tusk_api.url, and TUSK_API_KEY or tusk login are set.

If you have any questions, feel free to open an issue or reach us at support@usetusk.ai.

Resources

• Architecture overview
• Configuration

Development

See CONTRIBUTING.md.

License

See LICENSE.