Command: tusk init
Relevant source files
The following files were used as context for generating this wiki page:
The tusk init command launches an interactive onboarding wizard to help users configure Tusk Drift for their service. Its primary purpose is to gather necessary information about the user's project and generate a .tusk/config.yaml file. This process is handled by a Terminal User Interface (TUI) built with the Bubble Tea framework.
The command first validates that it's being run in a supported project directory (e.g., a Node.js project with a package.json). It then guides the user through a series of questions to determine service name, port, start commands, and Docker usage. Upon completion, it presents a summary of the configuration and, with user confirmation, saves it to disk. There is also an experimental AI-powered version, tusk exp init, which automates this process.
Sources: README.md, internal/tui/onboard/README.md, internal/tui/onboard/view.go:17-42
Architecture
The tusk init command's logic is primarily contained within the internal/tui/onboard package. It follows a Model-View-Update (MVU) architecture, which is characteristic of Bubble Tea applications.
Sources: internal/tui/onboard/README.md
Core Components
The following diagram illustrates the key components of the onboarding wizard and their interactions.
This diagram shows that the tusk init command calls onboard.Run to start the TUI. The TUI state is managed by the Model, which uses a Flow Manager to progress through a series of Steps. User input triggers the Update logic, which modifies the Model, and the View logic renders the Model's state to the terminal.
Sources: cmd/init.go, internal/tui/onboard/run.go, internal/tui/onboard/README.md
The table below describes the responsibility of each key file in the onboard package.
| File | Description |
|---|---|
run.go | The entry point for the wizard. Initializes the Bubble Tea model and runs the TUI application. |
model.go | Defines the Model struct, which holds the entire state of the wizard, including user inputs and current step. |
flow.go | Defines the Step interface and the Flow struct that manages the sequence of steps. |
steps.go | Contains the concrete implementation of each step in the wizard (e.g., ServiceNameStep, DockerSetupStep). |
update.go | Handles user input (key presses) and state transitions, such as advancing to the next step or going back. |
view.go | Renders the TUI for the current step based on the model's state. |
config.go | Defines the Config struct and contains the logic for generating the final config.yaml file from the model's state. |
Sources: internal/tui/onboard/README.md
The Step Interface
Each screen in the wizard is an implementation of the Step interface. This interface defines a contract for how a step presents information, collects input, validates data, and updates the application state.
type Step interface {
ID() onboardStep
InputIndex() int
Question(*Model) string
Description(*Model) string
Default(*Model) string
Validate(*Model, string) error
Apply(*Model, string)
Help(*Model) string
ShouldSkip(*Model) bool
Clear(*Model)
}
Sources: internal/tui/onboard/flow.go:10-21
| Method | Description |
|---|---|
ID() | Returns a unique identifier for the step. |
InputIndex() | Returns the index of the text input field to use, or -1 for non-input steps. |
Question() | The main prompt displayed to the user. |
Description() | Additional explanatory text shown below the question. |
Default() | Provides a default value if the user presses Enter without typing. |
Validate() | Validates user input. Returns an error if the input is invalid. |
Apply() | Updates the main Model with the validated input. |
Help() | Returns the help text to display in the TUI footer. |
ShouldSkip() | A predicate to determine if the step should be skipped based on the current state. |
Clear() | Resets the state associated with this step when the user navigates backward. |
Sources: internal/tui/onboard/README.md, internal/tui/onboard/flow.go:10-21
Execution Flow
The tusk init command follows a linear, step-by-step process to gather information.
This flowchart outlines the user's journey through the init wizard, from initial validation to the final configuration file being saved.
Sources: internal/tui/onboard/steps.go:4-21, internal/tui/onboard/view.go:17-42, 120-151
Key Wizard Steps
The wizard is composed of a predefined list of steps. Some steps can be skipped based on previous answers.
| Step ID | Purpose | Source |
|---|---|---|
stepValidateRepo | Checks if the current directory is a supported project type (e.g., has package.json). | internal/tui/onboard/steps.go:24 |
stepIntro | Welcomes the user and explains the purpose of the wizard. | internal/tui/onboard/steps.go:33 |
stepSDKCompatibility | Asks the user to confirm if their service dependencies are compatible with the Tusk Drift SDK. | internal/tui/onboard/steps.go:44 |
stepDockerSetup | Asks if the service will be run with Docker, which influences communication settings. | internal/tui/onboard/steps.go:111 |
stepDockerType | If Docker is used, asks whether it's Docker Compose or a Dockerfile. | internal/tui/onboard/steps.go:123 |
stepServiceName | Prompts for the service's name. | internal/tui/onboard/steps.go:133 |
stepServicePort | Prompts for the port the service runs on. | internal/tui/onboard/steps.go:141 |
stepStartCommand | Prompts for the command to start the service. | internal/tui/onboard/steps.go:154 |
stepReadinessCommand | Prompts for the command to check if the service is ready. | internal/tui/onboard/steps.go:168 |
stepConfirm | Displays the generated YAML configuration and asks for final confirmation. | internal/tui/onboard/steps.go:192 |
stepDone | Confirms that the configuration has been saved and provides next steps. | internal/tui/onboard/steps.go:200 |
Sources: internal/tui/onboard/steps.go
Configuration Generation
After the user confirms the settings in the stepConfirm view, the wizard generates a config.yaml file inside a .tusk directory.
Sources: internal/tui/onboard/config.go:13, 145-148
Config Structure
The generated configuration is based on the Config struct. The diagram below shows its structure.
This class diagram details the Go structs that are serialized into the final config.yaml file.
Sources: internal/tui/onboard/config.go:16-64
State-to-Config Mapping
The getCurrentConfig() function in config.go is responsible for mapping the state from the TUI Model (which holds user answers) to the Config struct.
func (m *Model) getCurrentConfig() Config {
// ...
cfg := Config{
Service: Service{
Name: m.ServiceName,
Port: m.currentPortInt(),
Start: Start{
Command: m.StartCmd,
},
Readiness: Readiness{
Command: m.ReadinessCmd,
Timeout: timeout,
Interval: interval,
},
},
// ... other fields
}
// ...
return cfg
}
This function populates a Config object with values like m.ServiceName, m.ServicePort, and m.StartCmd that were collected from the user during the wizard flow. This object is then marshaled into YAML and written to disk.
Sources: internal/tui/onboard/config.go:66-128
Experimental AI-Powered Init
The tusk exp init command provides an alternative, AI-powered setup flow. Instead of a manual wizard, it uses an AI agent (currently Claude) to inspect the codebase and automatically generate the configuration.
This agent operates in a series of phases, managed by the PhaseManager.
This flowchart shows the sequence of phases the AI agent executes to configure the project, from language detection to final testing and reporting.
Sources: internal/agent/agent.go:171-205, internal/agent/phases.go:264-274
The agent uses a set of "tools" to interact with the local environment, such as read_file, run_command, and write_file. Each phase has specific instructions and a list of available tools to accomplish its goal. For example, the "Gather Project Info" phase for a Node.js project is instructed to find the package manager, entry point, start command, and port by inspecting package.json and other source files.
Sources: internal/agent/executor.go, internal/agent/prompts/phase_gather_info_nodejs.md
Conclusion
The tusk init command is the primary entry point for integrating a new service with Tusk Drift. It provides a user-friendly, interactive TUI to create the essential .tusk/config.yaml file. Its step-based architecture is extensible, and the experimental AI-powered alternative demonstrates a path toward fully automated project setup. This initial configuration is critical for all subsequent Tusk Drift operations, including tusk run.