Project Configuration (.tusk/config.yaml)
Relevant source files
The following files were used as context for generating this wiki page:The .tusk/config.yaml file is the central configuration for the Tusk Drift CLI. It defines all the necessary parameters for running, testing, and recording a service. This file specifies how to start and stop the service, check its readiness, configure trace recording, and connect to Tusk Drift Cloud.
This configuration is typically generated and managed through one of the CLI's interactive setup wizards: the standard onboarding wizard (tusk init) or the AI-powered agent (tusk exp init). It can also be created and modified manually. The file is expected to be located in a .tusk directory at the root of the service's repository.
Sources: internal/config/config.go, README.md:112-116, internal/tui/onboard/config.go:13-16
Configuration Generation
The config.yaml file is created and populated through two primary mechanisms within the CLI.
Interactive Onboarding Wizard (tusk init)
The tusk init command launches a terminal UI (TUI) that guides the user through a series of questions to gather the required configuration values. The wizard dynamically suggests default values based on project inspection (e.g., detecting package.json or Docker files).
The flow of the wizard is defined by a series of steps, each responsible for collecting a piece of information.
This diagram illustrates the step-by-step process of the tusk init onboarding wizard.
At the confirmation step, the wizard displays the generated YAML for user review. Upon approval, it saves the configuration to .tusk/config.yaml, prepending a header comment with a link to the documentation.
Sources: internal/tui/onboard/view.go:102-125, internal/tui/onboard/config.go:136-140
AI Setup Agent (tusk exp init)
The experimental tusk exp init command uses an AI agent to automatically detect project settings and generate the configuration. The agent follows a series of phases, including Gather Project Info and Create Config. During the Create Config phase, the agent uses the write_file tool to create .tusk/config.yaml based on a predefined template and the information it gathered.
This sequence diagram shows the AI agent's process for creating the configuration file.
Configuration Schema
The structure of config.yaml is defined by Go structs in internal/config/config.go. The root Config object contains several nested sections that organize the settings.
This diagram shows the relationship between the main configuration structs.
Sources: internal/config/config.go:18-62
Top-Level Sections
| Section | Description |
|---|---|
service | Defines the service under test, including how to start, stop, and check its health. |
traces | Configures the location for storing recorded trace files. |
test_execution | Settings related to the execution of replay tests. |
recording | Parameters for the recording phase, such as sampling rate. |
tusk_api | Configuration for connecting to the Tusk Drift Cloud API. |
Sources: internal/config/config.go:19-25
service
This section contains all parameters related to the service being tested.
| Field | Type | Description | Default |
|---|---|---|---|
id | string | The Tusk Cloud observable service ID. Added by tusk init-cloud. | (empty) |
name | string | The name of the service. | Inferred from directory name or package.json. |
port | int | The port the service listens on. | Inferred from common ports (e.g., 3000, 8000). |
start | object | Contains the command to start the service. | See below. |
stop | object | (Optional) Contains the command to stop the service. Used for Docker setups. | See below. |
communication | object | (Optional) Defines communication method between CLI and SDK. Used for Docker. | See below. |
readiness_check | object | Defines the command and parameters for checking if the service is ready. | See below. |
Sources: internal/config/config.go:27-37, internal/tui/onboard/config.go:72-91
service.start
| Field | Type | Description | Default |
|---|---|---|---|
command | string | The shell command to start the service for testing. | Inferred from package.json scripts (npm run start) or Docker type. |
Sources: internal/config/config.go:39-41, internal/tui/onboard/steps.go:171-176
service.stop (Optional)
This is primarily used for Docker-based services.
| Field | Type | Description | Default |
|---|---|---|---|
command | string | The shell command to stop the service. | docker compose down for Docker Compose. |
Sources: internal/config/config.go:43-45, internal/tui/onboard/config.go:111-116
service.communication (Optional)
This is required for Docker-based services to allow the CLI to communicate with the SDK inside the container.
| Field | Type | Description | Default |
|---|---|---|---|
type | string | The communication protocol. | tcp |
tcp_port | int | The TCP port for the mock server. | 9001 |
Sources: internal/config/config.go:47-51, internal/tui/onboard/config.go:117-121
service.readiness_check
| Field | Type | Description | Default |
|---|---|---|---|
command | string | Command to execute to check if the service is ready. | curl -fsS http://localhost:{port}/health (port is substituted). |
timeout | string | Maximum time to wait for the service to become ready. | 30s |
interval | string | How often to run the readiness check. | 1s |
Sources: internal/config/config.go:53-57, internal/tui/onboard/config.go:73-79
recording
This section controls the behavior of the SDK during the recording phase. These values can be configured via the tusk init-cloud wizard.
| Field | Type | Description | Default |
|---|---|---|---|
sampling_rate | float64 | The percentage of requests to record (e.g., 1.0 for 100%, 0.1 for 10%). | 1.0 |
export_spans | bool | If true, uploads trace data to Tusk Drift Cloud. | false |
enable_env_var_recording | bool | If true, records environment variables for more accurate replay. | true |
Sources: internal/config/config.go:64-68, internal/tui/onboard-cloud/steps.go:323-334, internal/tui/onboard/config.go:103-107
traces
| Field | Type | Description | Default |
|---|---|---|---|
dir | string | The directory where recorded trace files (.jsonl) are stored. | .tusk/traces |
Sources: internal/config/config.go:60-62, internal/tui/onboard/config.go:92-94
test_execution
| Field | Type | Description | Default |
|---|---|---|---|
timeout | string | The timeout for a single test execution. | 30s |
Sources: internal/config/config.go:59-61, internal/tui/onboard/config.go:99-101
tusk_api (Optional)
| Field | Type | Description | Default |
|---|---|---|---|
url | string | The base URL for the Tusk Drift Cloud API. | https://api.usetusk.ai |
Sources: internal/config/config.go:70-72, internal/tui/onboard/config.go:95-97
Configuration Updates
The config.yaml file is designed to be updated by CLI commands, such as tusk init-cloud. The update process carefully reads the existing YAML, modifies specific nodes, and writes it back, preserving comments and structure.
This sequence diagram shows how a cloud configuration setting is updated in config.yaml.
The update logic uses the gopkg.in/yaml.v3 library, which allows for manipulation of the YAML document as a node tree. This ensures that comments and original formatting are preserved as much as possible during automated updates.
Sources: internal/tui/onboard-cloud/save.go:23-26, internal/tui/onboard-cloud/save.go:66-72