Home
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- CONTRIBUTING.md
- internal/agent/README.md
- internal/agent/agent.go
- internal/agent/executor.go
- internal/agent/phases.go
- internal/agent/prompts/phase_check_compatibility.md
- internal/agent/prompts/phase_gather_info_nodejs.md
- internal/agent/prompts/system.md
- internal/tui/onboard/README.md
- internal/tui/onboard/steps.go
- internal/tui/onboard/view.go
- internal/tui/onboard-cloud/steps.go
- scripts/release.sh
- internal/tui/onboard/manifest.go
- internal/agent/prompts/phase_summary.md
- internal/agent/prompts/phase_cloud_summary.md
Tusk Drift is an API test record-and-replay system designed to generate realistic tests from actual traffic. The tusk-drift-cli is the command-line interface that orchestrates local and CI test runs, coordinating with a Tusk Drift SDK integrated into a service and the optional Tusk Drift Cloud platform. The core principle is to record traces of HTTP requests, database queries, and other external calls in a live environment (production/staging) and then replay these traces locally to validate that the service behaves consistently.
This system is composed of three main parts: the CLI, language-specific SDKs (e.g., for Node.js), and the Tusk Drift Cloud for advanced features like test storage, analysis, and CI/CD integration. The CLI provides tools for initializing projects, running tests, and managing traces.
Sources: README.md:3-5, internal/agent/prompts/system.md:3-7
Features
The Tusk Drift CLI offers several key features to facilitate record-and-replay testing.
| Feature | Description |
|---|---|
| Trace Replay | Replays recorded traces against a service under test. |
| Deterministic I/O | Utilizes a local mock server to provide deterministic responses for outbound I/O during replays. |
| JSON Comparison | Compares JSON responses and supports dynamic field rules for values like UUIDs and timestamps. |
| Tusk Drift Cloud Integration | Fetches and replays tests stored in the cloud, and uploads results for intelligent regression analysis. |
Sources: README.md:19-23
Installation
Quick Install (Linux/macOS)
The recommended installation method is via a shell script:
curl -fsSL https://cli.usetusk.ai/install.sh | sh
For Linux, bubblewrap and socat are required for replay sandboxing. Without them, network isolation is disabled.
Sources: README.md:32-40
Other Installation Methods
- Windows: It is recommended to use WSL and follow the Linux installation. Native Windows installation requires manual download and path configuration.
- Build from source: The project can be built from source using Go 1.25+ and
make.
git clone https://github.com/Use-Tusk/tusk-drift-cli.git
cd tusk-drift-cli
make deps
make build
Sources: README.md:46-79
Core Concepts
Tusk Drift operates in two distinct phases: Recording and Replaying.
This diagram illustrates the two main operational modes of Tusk Drift.
Recording
During the recording phase, the service runs with the TUSK_DRIFT_MODE=RECORD environment variable. The integrated Tusk SDK intercepts and records traces of activities like HTTP requests/responses, database queries, and other external calls. These traces are typically saved as .jsonl files. Only requests with content types like application/json and text/plain are recorded; text/html and other formats are excluded.
Sources: internal/agent/prompts/system.md:41-46
Replay
During the replay phase, the tusk run command is used. The CLI starts the service with the SDK in replay mode, which intercepts outbound calls and directs them to a local mock server. This server provides deterministic responses based on the previously recorded traces. The CLI then compares the new responses from the service with the original recorded responses to detect any deviations or regressions.
Sources: internal/agent/prompts/system.md:48-54
Project Setup
Tusk Drift provides two primary methods for setting up a project: a TUI-based onboarding wizard and an experimental AI-powered setup agent.
Onboarding Wizard (tusk init)
The tusk init command launches an interactive Terminal UI (TUI) wizard, built with Bubble Tea, to guide users through the configuration process. The wizard asks a series of questions to gather necessary information about the service.
Sources: README.md:83-86, internal/tui/onboard/README.md:3-8
The wizard follows a series of steps to configure the project, as shown in the diagram below.
Diagram of the tusk init wizard flow.
Upon completion, the wizard generates a .tusk/config.yaml file and, if applicable, a docker-compose.tusk-override.yml file.
Sources: internal/tui/onboard/steps.go:4-18, internal/tui/onboard/README.md:200-201
AI-Powered Setup (tusk exp init)
This experimental feature uses an AI agent (Claude) to automate the setup process. The agent interacts with the project's codebase to detect settings, install the SDK, and create configuration files.
Sources: internal/agent/README.md:3-4
The AI agent is composed of several key components that work together to manage the setup flow.
High-level architecture of the AI setup agent.
The agent operates in a series of defined phases, each with a specific goal.
Flowchart of the AI agent's setup phases.
To accomplish its tasks, the agent has access to a variety of tools.
| Tool Name | Description |
|---|---|
read_file | Read the contents of a file. |
write_file | Write content to a file. |
list_directory | List files and directories. |
grep | Search for a pattern in files. |
run_command | Run a one-shot shell command. |
start_background_process | Start a long-running process like a server. |
ask_user | Ask the user a question. |
transition_phase | Complete the current phase and move to the next. |
abort_setup | Abort the setup process gracefully. |
Sources: internal/agent/README.md:8-27, internal/agent/phases.go:304-314, internal/agent/executor.go:11-46
Tusk Drift Cloud
Tusk Drift Cloud extends the local testing capabilities by providing a centralized platform for test storage, intelligent deviation analysis, and CI/CD integration. It allows teams to automatically record traces from live environments and run them as part of their CI pipeline.
Sources: README.md:107-112
The interaction between the local CLI, the service, and Tusk Drift Cloud is depicted below.
Sequence diagram showing the Tusk Drift Cloud workflow.
The tusk cloud-init command launches a dedicated wizard to connect a project to Tusk Drift Cloud. The steps include authentication, repository detection, service creation, and API key generation.
Sources: README.md:114-116, internal/tui/onboard-cloud/steps.go:484-497
Usage
Common commands for interacting with the CLI.
| Command | Description |
|---|---|
tusk init | Starts the interactive onboarding wizard to create a .tusk/config.yaml file. |
tusk cloud-init | Starts the wizard to set up Tusk Drift Cloud integration. |
tusk run | Runs tests by replaying traces. Can be run with local or cloud traces. |
tusk list | Lists available traces, either locally or from the cloud. |
Key flags:
--trace-dir: Specify the directory for local traces.--trace-file: Specify a single trace file to run.--filter: Filter which traces to run using a regex pattern.--cloud: Use Tusk Drift Cloud for listing or running traces.--enable-service-logs: Save service logs during replay to.tusk/logs.
The CLI uses a .tusk directory in the project root to store configuration, traces, results, and logs.
Sources: README.md:83-149
Development and Contribution
The project is open to contributions. The development workflow relies on a Makefile for common tasks.
| Make Target | Description |
|---|---|
make build | Build the binary (./tusk). |
make run | Build and run the application. |
make test-ci | Run tests for all packages, as done in CI. |
make fmt | Format the Go code. |
make lint | Run the golangci-lint linter. |
Releases are automated using GoReleaser and triggered by pushing a new version tag created with the ./scripts/release.sh script.
Sources: CONTRIBUTING.md:16-25, scripts/release.sh
Project Structure
The repository is organized into several key directories.
| Path | Description |
|---|---|
cmd/ | Contains the Cobra command definitions that form the CLI's entry points. |
internal/agent/ | Implements the AI-powered setup agent, including phases, tools, and Claude API client. |
internal/api/ | Contains the protobuf-over-HTTP client for communicating with the Tusk backend. |
internal/config/ | Manages configuration loading using Koanf. |
internal/runner/ | Contains the core test execution logic, including the Unix socket server and response matcher. |
internal/tui/ | Implements the Bubble Tea-based interactive UIs for test running and onboarding. |
docs/ | Contains architecture and configuration documentation. |
Sources: CONTRIBUTING.md:42-50, internal/tui/onboard/README.md:11-22, internal/agent/README.md:29-37