Global CLI Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The tusk-drift-cli uses a project-specific YAML configuration file, typically located at .tusk/config.yaml, to define how to run, test, and record a service. This file is the central source of truth for the CLI's operations within a given project repository. It is generated by the tusk init command and can be modified to fine-tune behavior.
The configuration is loaded using the Koanf library, which allows for a layered approach, though the primary provider is the YAML file. The system is designed to find the config file by searching upwards from the current directory.
Sources: internal/config/config.go:210-244, internal/tui/onboard/config.go:16-19, README.md:120-122
Configuration Loading
The configuration is loaded and managed by the internal/config package. It employs a singleton pattern to ensure the configuration is loaded only once per execution.
The loading process follows these steps:
- A call to
config.Get()orconfig.Load()is made. - A
sync.Mutexlock is acquired to prevent race conditions. - If the config has already been loaded, the cached version is returned.
- If not loaded, the
findConfigFile()function searches for.tusk/config.yaml(or.yml) by traversing up the directory tree from the current working directory. - The file is parsed using a YAML parser.
- Environment variables (e.g.,
TUSK_API_URL,TUSK_TRACES_DIR) can override values from the file. - Default values are applied for any missing fields.
- The final configuration is validated and cached for subsequent calls.
Sources: internal/config/config.go:88-132, internal/config/config.go:135-147
The following diagram illustrates the config loading flow.
Configuration Schema
The main configuration is defined by the Config struct in internal/config/config.go. It is composed of several nested structs, each representing a top-level key in the YAML file.
Sources: internal/config/config.go:27-38
This diagram shows the relationship between the main Config struct and its components.
Top-Level Sections
| Section | Struct | Description | Source File |
|---|---|---|---|
service | ServiceConfig | Defines the service under test, including its name, port, and start/stop commands. | internal/config/config.go:40-48 |
tusk_api | TuskAPIConfig | Specifies the URL for the Tusk Cloud API. | internal/config/config.go:67-69 |
comparison | ComparisonConfig | Configures rules for comparing actual vs. expected responses during replay. | internal/config/config.go:75-81 |
test_execution | TestExecutionConfig | Controls test execution parameters like concurrency and timeouts. | internal/config/config.go:71-74 |
recording | RecordingConfig | Manages recording behavior, such as sampling rate. | internal/config/config.go:83-87 |
replay | ReplayConfig | Reserved for future replay-specific options. | internal/config/config.go:89-91 |
traces | TracesConfig | Specifies the directory for storing recorded traces. | internal/config/config.go:93-95 |
results | ResultsConfig | Specifies the directory for storing test results. | internal/config/config.go:97-99 |
service
This is the most critical section, defining the service being tested.
| Field | Type | Description | Default |
|---|---|---|---|
id | string | The observable service ID from Tusk Cloud. | |
name | string | A human-readable name for the service. | |
port | int | The port the service listens on. | 3000 |
start | StartConfig | Contains the command to start the service. | |
stop | StopConfig | Contains the command to stop the service (especially for Docker). | |
readiness_check | ReadinessConfig | Defines the command and timing for checking if the service is ready. | |
communication | CommunicationConfig | Configures how the CLI communicates with the SDK (e.g., unix socket vs. tcp). | auto |
Sources: internal/config/config.go:40-65, internal/config/config.go:169-170, [internal/config/config.go:183-189]
recording
This section controls how traces are recorded.
| Field | Type | Description | Default |
|---|---|---|---|
sampling_rate | float64 | The percentage of requests to record (0.0 to 1.0). | 0.1 |
export_spans | *bool | Whether to export trace spans to Tusk Cloud. | false |
enable_env_var_recording | *bool | Whether to record environment variables during tracing. | false |
Sources: internal/config/config.go:83-87, [internal/config/config.go:174-182]
Generation and Modification
tusk init Onboarding Wizard
The primary method for creating the .tusk/config.yaml file is through the tusk init command, which launches an interactive onboarding wizard. This wizard guides the user through a series of steps to gather the necessary information.
The wizard's state is held in the onboard.Model struct, which collects user input for service name, port, start command, etc. Upon completion, the saveConfig() function assembles the onboard.Config struct and writes it to .tusk/config.yaml.
A header comment linking to the full configuration documentation is prepended to the generated file.
Sources: internal/tui/onboard/config.go:111-140, internal/tui/onboard/steps.go, [internal/tui/onboard/view.go:100-109]
This sequence diagram shows how the tusk init wizard creates the config file.
tusk init-cloud and tusk exp init
The cloud onboarding wizard (tusk init-cloud) and the experimental AI agent (tusk exp init) can also modify the .tusk/config.yaml file.
tusk init-cloud: This wizard updates the configuration with cloud-specific settings likeservice.idand therecordingparameters (sampling_rate,export_spans). It reads the existing YAML, modifies it in memory usingyaml.Nodeto preserve comments and structure, and writes it back.tusk exp init: The AI agent uses thewrite_filetool to create or overwrite the config file based on the information it gathers.
Sources: internal/tui/onboard-cloud/save.go:12-20, internal/tui/onboard-cloud/steps.go:420-424, internal/agent/agent.go:486-491, [internal/agent/phases.go:300-311]