CLI Internal Architecture

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/system.md
• internal/tui/onboard/README.md
• internal/tui/onboard/config.go
• internal/tui/onboard/steps.go
• internal/tui/onboard-cloud/steps.go
• internal/tui/onboard-cloud/save_test.go
• scripts/release.sh

The Tusk Drift CLI is a Go application designed to orchestrate local and CI-based API test runs. It features a modular architecture with distinct components for command-line parsing, user interaction via Terminal User Interfaces (TUIs), and an AI-powered setup agent. The primary goal is to configure a user's service for test recording and replaying, either locally or integrated with Tusk Drift Cloud.

The CLI is built around several key commands, including tusk run for executing tests, tusk init for guided local setup, and tusk cloud-init for cloud integration. A notable experimental feature is tusk exp init, which uses an AI agent to automate the entire setup process.

Sources: README.md, CONTRIBUTING.md:15-26

High-Level Component Overview

The codebase is organized into several key directories, each responsible for a specific part of the CLI's functionality.

This diagram shows the high-level interaction between the user, the main command parsing logic, and the internal packages.

Sources: CONTRIBUTING.md:28-36, internal/agent/README.md:9-24

Code Structure

Directory	Description
cmd/	Contains the Cobra command definitions, which serve as the entry points for all CLI functionality (e.g., run, init).
internal/tui/	Implements the interactive onboarding wizards (tusk init and tusk cloud-init) using the Bubble Tea framework.
internal/agent/	Contains the AI-powered setup agent (tusk exp init), which uses an LLM to automate configuration.
internal/runner/	Manages the core test replay logic, including the Unix socket server, test matching, and response comparison.
internal/config/	Handles loading and parsing the .tusk/config.yaml file using Koanf.
internal/api/	Implements the protobuf-over-HTTP client for communicating with the Tusk Drift Cloud backend.
internal/auth/	Manages the Auth0 device code flow for authenticating users with Tusk Drift Cloud.

Sources: CONTRIBUTING.md:28-36

Onboarding Wizards

The CLI includes two primary TUI-based wizards to guide users through configuration: tusk init for local setup and tusk cloud-init for cloud integration. Both are built using the Bubble Tea framework.

Sources: internal/tui/onboard/README.md:3, README.md:121-123

tusk init (Local Setup)

This wizard guides the user through creating the initial .tusk/config.yaml file. It is structured as a sequence of steps, where each step is an implementation of the Step interface.

Sources: internal/tui/onboard/README.md:15-27

Step Interface

The Step interface defines the behavior for each screen in the wizard.

This diagram shows the Step interface, a BaseStep providing default implementations, and an example ServiceNameStep that overrides specific methods.

Sources: internal/tui/onboard/README.md:15-39, internal/tui/onboard/steps.go:132-138

Wizard Flow

The wizard progresses through a predefined list of steps. User input is handled in an update loop, which validates input, applies it to the state model, and advances to the next step.

This flowchart illustrates the simplified logical flow of the tusk init command.

Sources: internal/tui/onboard/steps.go:3-20, internal/tui/onboard/view.go:18-137

tusk cloud-init (Cloud Setup)

This wizard follows a similar architecture to tusk init but focuses on integrating the local project with Tusk Drift Cloud. It reads the existing .tusk/config.yaml and adds cloud-specific settings.

Sources: internal/tui/onboard-cloud/steps.go:27-38, README.md:121-123

Key steps in the cloud-init flow include:

1. Validating Local Config: Ensures .tusk/config.yaml exists.
2. Detecting Git Repository: Identifies the Git remote to associate with the cloud service.
3. Client Selection: Asks the user to select an organization if they belong to multiple.
4. Verifying Repository Access: Checks if the Tusk GitHub/GitLab app has access to the repository.
5. Creating Service: Registers the repository as an observable service in Tusk Cloud.
6. Creating API Key: Generates an API key for CI/CD authentication.
7. Configuring Recording: Sets cloud-specific recording parameters like sampling rate.
8. Saving Configuration: Updates .tusk/config.yaml with the new settings.

Sources: internal/tui/onboard-cloud/steps.go:215-220, internal/tui/onboard-cloud/save_test.go:121-137

AI-Powered Setup Agent

The tusk exp init command uses an AI agent to automate the setup process. The agent is orchestrated by the Agent struct and operates in a series of "phases," each with a specific goal.

Sources: internal/agent/README.md:3, internal/agent/agent.go:68-88

Agent Architecture

The agent's core loop iterates through phases, communicates with the Claude API, and executes "tools" to interact with the local environment.

This diagram from the agent's documentation illustrates the data flow between the main agent loop, phase manager, tool executors, and the Claude API.

Sources: internal/agent/README.md:7-29

Phases

The setup process is broken down into a sequence of phases managed by the PhaseManager. Each phase has a defined goal, a set of available tools, and instructions for the AI.

The default phases are:

1. Detect Language
2. Check Compatibility
3. Gather Project Info
4. Confirm App Starts
5. Instrument SDK
6. Create Config
7. Simple Test
8. Complex Test
9. Summary

Sources: internal/agent/phases.go:273-283

The agent transitions between phases by calling the transition_phase tool, which updates the agent's internal state with the results from the completed phase.

Sources: internal/agent/phases.go:240-269

Tools

Tools are functions the AI can call to interact with the user's system. The executor.go file defines a registry of available tools, their JSON schemas, and their corresponding Go functions.

Tool Name	Description	Requires Confirmation
read_file	Read the contents of a file.	No
write_file	Write content to a file.	Yes
patch_file	Apply a targeted edit to an existing file.	Yes
run_command	Run a one-shot shell command.	Yes
start_background_process	Start a long-running process (e.g., a server).	Yes
http_request	Make an HTTP request to test an endpoint.	Yes
ask_user	Ask the user a question and wait for a response.	No
transition_phase	Complete the current phase and move to the next.	No
abort_setup	Abort the setup process gracefully if the project is unsupported.	No

Sources: internal/agent/executor.go:10-40, internal/agent/executor.go:88-301

When a tool requires confirmation, the TUI prompts the user for permission before execution. The user can approve, deny, or approve all future actions.

Sources: internal/agent/agent.go:618-656, internal/agent/tui.go:653-659

State and Resumption

The agent maintains its state in a State struct, which is serialized to JSON and included in the prompt to the LLM. This state includes discovered information like project type, start command, and port.

Sources: internal/agent/phases.go:90-181

To handle interruptions, the agent saves its progress to a PROGRESS.md file in the .tusk directory. On subsequent runs, it reads this file to parse completed phases and discovered information, allowing it to resume where it left off.

Sources: internal/agent/agent.go:193-242, internal/agent/agent.go:946-1120

Configuration

The CLI's behavior is primarily controlled by a .tusk/config.yaml file. This file is created by the tusk init wizard or the AI agent.

Sources: internal/tui/onboard/config.go:13-14

config.yaml Structure

The configuration is composed of several top-level sections:

# Tusk Drift configuration
# For all configuration options, see:
# https://github.com/Use-Tusk/tusk-drift-cli/blob/main/docs/configuration.md

service:
  name: my-service
  port: 3000
  start:
    command: npm run start
  readiness_check:
    command: curl --fail http://localhost:3000/health
    timeout: 30s
    interval: 1s

recording:
  sampling_rate: 1.0
  export_spans: false
  enable_env_var_recording: true

traces:
  dir: .tusk/traces

test_execution:
  timeout: 30s

tusk_api:
  url: https://api.usetusk.ai

Section	Description
service	Defines how to run and interact with the user's service, including start commands and readiness checks.
recording	Configures parameters for the recording phase, such as the sampling rate.
traces	Specifies the directory where local trace files are stored.
test_execution	Sets global timeouts for test runs.
tusk_api	Contains settings for interacting with Tusk Drift Cloud, such as the API URL and service ID (added by cloud-init).

Sources: internal/tui/onboard/config.go:16-52, internal/tui/onboard/config.go:183-187

Release Process

Releases are automated using GoReleaser and triggered by pushing a new version tag to the main branch. The scripts/release.sh script is used to manage this process.

The script performs several pre-flight checks:

• Ensures the working directory is clean.
• Verifies the local main branch is up-to-date with the remote.
• Runs tests (make test-ci) and the linter (make lint).

It then calculates the next version number (patch or minor), prompts for confirmation, and pushes the new tag.

Sources: scripts/release.sh:6-92, CONTRIBUTING.md:120-132