Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• internal/agent/README.md
• internal/agent/agent.go
• internal/agent/executor.go
• internal/agent/phases.go
• internal/tui/onboard/README.md
• internal/tui/onboard/config.go
• internal/tui/onboard/steps.go
• internal/tui/onboard/view.go
• internal/tui/onboard-cloud/steps.go
• internal/agent/prompts/system.md
• internal/agent/prompts/phase_gather_info_nodejs.md
• internal/agent/prompts/phase_check_compatibility.md
• internal/agent/prompts/phase_summary.md
• internal/tui/onboard-cloud/save_test.go

Tusk Drift is an API test record/replay system that allows you to run realistic tests generated from real traffic. The tusk-drift-cli is the command-line interface that orchestrates local and CI test runs, working with a Tusk Drift SDK in your service and the Tusk Drift Cloud platform. This guide covers installation, initial project setup, and running tests.

Getting started involves two main commands: tusk init to configure your project and tusk run to execute tests. For cloud integration, tusk cloud-init is used. For more detailed information, see the Configuration and Tusk Drift Cloud documentation.

Sources: README.md:3-4, README.md:100-103

Installation

You can install the tusk-drift-cli via a script, manual download, or by building from source.

Sources: README.md:31

Quick Install (Linux/macOS)

The recommended method is using the install script, which downloads the latest version.

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

For Linux users, bubblewrap and socat are required for replay sandboxing, which provides network isolation. Without them, sandboxing is disabled.

Sources: README.md:36-38, README.md:43-47

Windows

For Windows, using WSL (Windows Subsystem for Linux) is recommended, which allows you to follow the Linux installation steps. A native Windows installation is also possible by downloading the binary from the GitHub Releases page.

Sources: README.md:52-54

Build from Source

If you have Go 1.25+ installed, you can build the CLI from source.

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

Sources: README.md:83-88, CONTRIBUTING.md:11

Project Initialization

To begin, navigate to your service's root directory and run tusk init. This command launches a wizard to help create the necessary .tusk/config.yaml file. The CLI offers two main initialization methods: a standard interactive wizard and an experimental AI-powered agent.

Sources: README.md:93-97

Standard Onboarding Wizard (tusk init)

The standard tusk init command starts an interactive Terminal UI (TUI) built with Bubble Tea. This wizard guides you through a series of questions to generate the .tusk/config.yaml file.

The wizard flow is a series of steps, each responsible for gathering a piece of information, validating it, and applying it to the configuration model.

Sources: internal/tui/onboard/README.md:3-5, internal/tui/onboard/README.md:10-12

The diagram below shows the typical sequence of steps in the init wizard.

Sources: internal/tui/onboard/steps.go:3-16, internal/tui/onboard/view.go

The primary output is the .tusk/config.yaml file. Below are the key sections configured by the wizard.

Section	Key	Description	Default Value
service	name	The name of your service.	Inferred from directory name.
service	port	The port your service runs on.	Inferred from project files.
service	start.command	The command to start your service for replay.	Inferred from package.json scripts.
service	stop.command	The command to stop your service (if using Docker).	Inferred from Docker context.
service	readiness_check.command	A command to verify the service is ready.	curl --fail http://localhost:{port}
recording	sampling_rate	Percentage of requests to record (0.0-1.0).	1.0
traces	dir	Directory to store local trace files.	.tusk/traces
communication	type	tcp for Docker, otherwise Unix sockets are used.	tcp (if Docker is used)

Sources: internal/tui/onboard/config.go:19-68, internal/tui/onboard/steps.go

AI-Powered Setup (tusk exp init)

As an alternative, tusk exp init uses an AI agent to automate the setup process. The agent, powered by Claude, interacts with your codebase to detect settings, install the SDK, and create the configuration.

The agent operates in a series of phases, moving from detection to configuration and testing. Its progress is saved to .tusk/PROGRESS.md, allowing the setup to be resumed if interrupted.

Sources: internal/agent/README.md:3-4, internal/agent/agent.go:50-52, internal/agent/agent.go:731-734

The agent's workflow is structured into distinct, sequential phases.

Sources: internal/agent/phases.go:296-306, internal/agent/README.md:10-18

The agent uses a predefined set of "tools" to interact with the local environment. These tools allow it to perform actions like reading files, running commands, and asking the user for input.

Tool Name	Description
read_file	Read the contents of a file.
write_file	Write content to a file.
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 and get a response.
tusk_run	Execute tusk run to replay traces.
transition_phase	Complete the current phase and move to the next.
abort_setup	Gracefully exit the setup process if it cannot proceed.

Sources: internal/agent/executor.go:10-33, internal/agent/README.md:28-33

Running Tests (tusk run)

Once your project is configured and you have recorded traces, use the tusk run command to replay them. This command starts your service, intercepts outbound I/O, and compares the new responses against the recorded ones.

By default, tusk run starts an interactive TUI. For CI/CD or scripting, you can use headless mode.

Sources: README.md:19-22, README.md:143-145

Common Usage

Command	Description
tusk run	Run all tests from the default local trace directory (.tusk/traces).
tusk run --trace-dir <path>	Specify a directory of trace files to run.
tusk run --trace-file <path>	Run a single trace file.
tusk run --trace-id <id>	Run a single trace by its ID.
tusk run --filter '<regex>'	Filter which traces to run based on a regex pattern.
tusk run --concurrency <N>	Set the number of parallel test executions.
tusk run --enable-service-logs	Save service logs to .tusk/logs.
tusk run --save-results	Save test results to .tusk/results.
tusk run --print	Run in headless mode with simple pass/fail output.

Sources: README.md:105-114, README.md:147-149

Tusk Drift Cloud

Tusk Drift Cloud provides storage for test traces, intelligent analysis of test failures, and automatic trace recording from live environments. To connect your local project to the cloud, use the tusk cloud-init command.

This command starts a separate onboarding wizard to configure cloud settings.

Sources: README.md:118-126, README.md:131-133

The cloud initialization flow is as follows:

Sources: internal/tui/onboard-cloud/steps.go:498-512

After setup, you can use cloud-specific flags with tusk commands:

• tusk list --cloud: List test suites stored in Tusk Drift Cloud.
• tusk run --cloud: Run tests using traces from Tusk Drift Cloud.

Sources: README.md:138-140, README.md:145-146

Project Directory (.tusk)

The CLI uses a .tusk directory in your project root to store all its artifacts.

• .tusk/config.yaml: The main configuration file.
• .tusk/traces/: Default directory for locally recorded traces.
• .tusk/results/: Default directory for saved test results (when using --save-results).
• .tusk/logs/: Stores service logs during test runs (when using --enable-service-logs).
• docker-compose.tusk-override.yml: Optional file generated for Docker Compose projects.
• .tusk/PROGRESS.md: Temporary file created by the AI agent to track setup progress.
• .tusk/SETUP_REPORT.md: Final report generated by the AI agent upon completion.

It is recommended to add .tusk/results, .tusk/logs, and potentially .tusk/traces (if using Tusk Drift Cloud primarily) to your .gitignore file.

Sources: README.md:151-163, internal/tui/onboard/config.go:15-16, internal/agent/agent.go:41, internal/agent/prompts/phase_summary.md:13