Command: tusk list

Relevant source files

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

• cmd/list.go
• cmd/short_docs/list.md
• README.md
• internal/agent/executor.go
• internal/agent/tools/cloud.go
• internal/tui/onboard-cloud/steps.go
• cmd/root.go

The tusk list command is a utility for inspecting recorded test traces. Its primary function is to display a summary of available traces from either a local directory or from Tusk Drift Cloud. This allows users to quickly see what tests have been captured and are available for replay with the tusk run command.

The command supports two main operating modes: listing local traces from the filesystem and listing cloud-based traces by fetching them from the Tusk Drift Cloud API. It can render output as a human-readable table in the terminal or as structured JSON for programmatic use. The command is also integrated into the AI Setup Agent as a tool to verify trace creation.

Sources: cmd/short_docs/list.md, README.md:144-148, internal/agent/executor.go:300-306

Command Definition and Flags

The list command is defined using the Cobra library. It is registered under the root tusk command.

Sources: cmd/list.go:27-35, cmd/root.go:25-32

// cmd/list.go:27-35
var listCmd = &cobra.Command{
	Use:   "list",
	Short: "List recorded traces",
	Long:  utils.RenderMarkdown(listContent),
	RunE: func(cmd *cobra.Command, args []string) error {
		// ... implementation ...
	},
}

The command's behavior can be modified with the following flags:

Flag	Shorthand	Description	Default Value
--cloud		List traces from Tusk Drift Cloud instead of local files.	false
--trace-dir		Directory to search for local traces.	.tusk/traces
--output-format		Output format. Can be table or json.	table
--print		Print output to stdout instead of using the interactive TUI.	false

Sources: cmd/list.go:142-147

Execution Flow

The command's execution logic branches based on whether the --cloud flag is provided. If true, it fetches traces from the Tusk Drift Cloud API. Otherwise, it scans a local directory for trace files. The final output is then formatted as either a table or JSON.

This diagram illustrates the high-level execution flow of the tusk list command.

Local Trace Listing

When run without the --cloud flag, the command executes the listLocalTraces function. This function scans the directory specified by --trace-dir (or the default .tusk/traces) for .jsonl files. It reads each file line by line, unmarshals the JSON trace data, and extracts key information to display.

The local trace listing displays the following columns:

• Trace ID
• Method
• Path
• Status
• Timestamp

Sources: cmd/list.go:73-111

Cloud Trace Listing

When the --cloud flag is used, the listCloudTraces function is called. This function requires the user to be authenticated with Tusk Drift Cloud. It initializes the cloud API client and sends a ListTraceTests request. The response contains a list of trace tests associated with the user's service, which are then formatted for display.

The cloud trace listing displays the following columns:

• Test ID
• Path
• Method
• Status
• Created At

This mode is recommended as a next step for users after completing the cloud setup wizard.

Sources: cmd/list.go:43-71, internal/tui/onboard-cloud/steps.go:420-424

Output Formats

The tusk list command provides two distinct output formats, controlled by the --output-format flag.

Table (Default)

By default, or when --output-format=table is specified, the command prints a formatted, human-readable table to the console. If the --print flag is not used, this is rendered within an interactive TUI.

Sources: cmd/list.go:61-68, cmd/list.go:100-108

JSON

When --output-format=json is used, the command outputs a JSON array of trace objects. This format is intended for scripting and programmatic consumption, such as by the AI agent. The --print flag is typically used with this format to ensure the JSON is written directly to stdout.

Sources: cmd/list.go:69-71, cmd/list.go:109-111

Usage in AI Agent

The tusk list command is exposed to the AI Setup Agent as a tool named tusk_list. This allows the agent to programmatically verify that traces have been successfully recorded after guiding a user through a test run.

Sources: internal/agent/executor.go:49

Tool Definition

The tool is defined in the agent's executor with a simple schema, as it requires no input parameters.

Sources: internal/agent/executor.go:300-306

// internal/agent/executor.go:300-306
ToolTuskList: {
    Name:        ToolTuskList,
    Description: "Run 'tusk list' to show available recorded traces. Use after recording to verify traces were captured.",
    InputSchema: json.RawMessage(`{
        "type": "object",
        "properties": {}
    }`),
},

Tool Execution

When the AI agent invokes the tusk_list tool, the agent's TuskTools.List method is called. This method executes the shell command tusk list --print --output-format=json, ensuring the agent receives a structured JSON response that it can parse and act upon.

The following sequence diagram shows how the AI agent uses the tusk_list tool.

Summary

The tusk list command is a fundamental part of the Tusk Drift CLI, providing essential visibility into the test traces that form the basis of the replay system. Its dual-mode (local/cloud) operation and flexible output formats (table/JSON) make it a versatile tool for both interactive user sessions and automated workflows, including the AI-driven setup process.

Sources: README.md:144-148, cmd/list.go