Installation

Relevant source files

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

• install.sh
• README.md
• CONTRIBUTING.md
• scripts/release.sh
• internal/tui/onboard/view.go
• internal/tui/onboard/README.md
• internal/agent/agent.go

The Tusk Drift CLI (tusk) is a standalone binary that orchestrates local and CI test runs. Installation involves acquiring this binary and placing it in your system's PATH. After installation, a project is configured for use with Tusk Drift by running an initialization command like tusk init, which creates the necessary configuration files.

This document covers the various methods for installing the tusk binary and the subsequent project initialization steps. For more details on the CLI's inner workings, see the Architecture Overview.

Sources: README.md:4, README.md:104-108, internal/tui/onboard/README.md:3

Installation Methods

There are three primary methods for installing the Tusk Drift CLI.

Method	Description	Use Case
Quick Install Script	Recommended. A curl command that automatically downloads and installs the correct binary for your system.	Most users on Linux and macOS.
Manual Download	Download a pre-built binary or archive from GitHub Releases.	Users on Windows (without WSL) or systems where the script is not suitable.
Build from Source	Compile the binary from the source code.	Developers contributing to the CLI or needing a custom build.

Sources: README.md:55, README.md:92, README.md:98

Quick Install (Recommended)

This method uses a shell script to detect the operating system and architecture, download the appropriate release artifact from GitHub, and install it.

Linux/macOS:

To install the latest version:

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

To install a specific version (e.g., v1.2.3):

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

Sources: README.md:58-65, install.sh:4-8

The installation script performs the following steps:

This diagram shows the execution flow of the install.sh script, from system detection to final installation.
Sources: install.sh

• OS/Architecture Detection: The script uses uname -s and uname -m to detect the operating system (Linux/Darwin) and architecture (x86_64/arm64).
• Version Selection: It installs the version specified as an argument, the TUSK_VERSION environment variable, or falls back to the latest version by checking https://cli.usetusk.ai/latest.txt or the GitHub API.
• Installation Directory: It attempts to install to /usr/local/bin. If that directory is not writable, it falls back to $HOME/.local/bin.
• PATH Check: After installation, it checks if the installation directory is in the user's $PATH and prints a warning if it is not.

Sources: install.sh:13-33, install.sh:36-54, install.sh:72-80, install.sh:87-93

Linux Dependencies

For replay sandboxing on Linux, additional dependencies are required. Without these, replays run without network isolation.

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

Sources: README.md:67-73

Manual Installation

Pre-built binaries for all supported platforms can be downloaded directly from the GitHub Releases page.

Windows

For native Windows installation (without WSL), download the appropriate .zip archive, extract tusk.exe, and move it to a directory that is included in your system's PATH.

Sources: README.md:77-93

Supported Platforms

The release workflow automatically builds binaries for the following platforms and architectures.

Operating System	GOOS	Architectures (GOARCH)
Linux	linux	amd64, arm64
macOS	darwin	amd64, arm64
Windows	windows	amd64, arm64

Sources: CONTRIBUTING.md:154-158

Build from Source

You can build the tusk binary directly from the source code. This is useful for development or for creating builds for unsupported platforms.

Requirements:

• Go 1.25+

Sources: CONTRIBUTING.md:11

Build Steps:

# 1. Clone the repository
git clone https://github.com/Use-Tusk/tusk-drift-cli.git
cd tusk-drift-cli

# 2. Install dependencies
make deps

# 3. Build the binary
make build

# The 'tusk' binary will be created in the root directory.
./tusk --help

Sources: CONTRIBUTING.md:14-17, README.md:99-103

Post-Installation: Project Initialization

After installing the tusk binary, you must initialize it within your service's repository. This step creates the .tusk/config.yaml file and other necessary configurations.

There are three main ways to initialize a project:

This diagram illustrates the different initialization commands and their corresponding setup flows.
Sources: README.md:107, README.md:133, internal/agent/agent.go:61

1. Standard Onboarding (tusk init): This is the standard, recommended method. It launches an interactive TUI wizard that guides you through creating the .tusk/config.yaml file. It detects project settings and asks for confirmation.
   Sources: README.md:107, internal/tui/onboard/README.md:3-4

2. Cloud Onboarding (tusk cloud-init): This command launches a wizard specifically for setting up Tusk Drift Cloud, which includes authentication, repository linking, and configuring cloud-based trace recording.
   Sources: README.md:133-135

3. AI-Powered Setup (tusk exp init): This experimental command runs an AI agent that attempts to automatically configure the project. It inspects the codebase to gather information, install the SDK, and create the configuration. Progress is saved to .tusk/PROGRESS.md to allow resuming an interrupted session.
   Sources: internal/agent/agent.go:61, internal/agent/agent.go:215-218

After a successful tusk init, the CLI provides the next steps, which typically include:

• Installing the language-specific Tusk Drift SDK.
• Initializing the SDK in your service.
• Recording the first traces.
• Running tests with tusk run.

Sources: internal/tui/onboard/view.go:128-149