Terminal UI and Formatting

Relevant source files

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

• internal/tui/progress.go
• internal/cli/render.go
• internal/cli/help_doc.go
• internal/cli/init.go
• internal/cli/up.go

The Terminal UI (TUI) and Formatting system in Docktree provides a rich, interactive, and highly structured command-line experience. It handles two primary modes of communication: a human-readable TTY mode featuring stylized text, progress indicators, and tables, and a machine-readable JSON mode for automation and AI agent integration.

The system is designed to provide real-time feedback during long-running Docker operations while ensuring that output remains consistent across different terminal widths and environments.

Architecture and Rendering Logic

Docktree utilizes a dual-renderer architecture. The humanRenderer manages sophisticated terminal formatting, including ANSI colors, symbols, and dynamic line wrapping, while a JSON encoder handles structured data output when the --json flag is present.

Rendering Flow

The following diagram illustrates how the system decides between human-readable TUI output and structured JSON based on the execution context.

Terminal Width Management

The system dynamically adjusts formatting based on the detected terminal width. This is crucial for table rendering and progress updates to prevent broken layouts on small screens.

• Width Detection: The termWidth function queries the underlying writer to determine available columns.
• Wrap Tracking: The StepPrinter tracks logical lines vs. actual terminal rows by calculating visible_width / terminal_width.

Sources: internal/cli/render.go:14-19, internal/tui/progress.go:28-40

Interactive Components

Docktree provides several UI primitives to handle complex state transitions and data presentation.

Step-Based Progress

The StepPrinter allows for sequential logging of operations, supporting headers, sub-steps, and status updates.

Component	Visual Representation	Purpose
Header	Bold Title + Dim Subtitle	Marks the start of a major operation (e.g., "Starting services...")
Done	✓ [message]	Indicates a successfully completed sub-task.
Active	◐ [message]	Shows the current task in progress.
Sub	Indented text	Provides granular detail for a specific step.

Sources: internal/tui/progress.go:42-88, internal/cli/up.go:50-55

Dynamic Spinners

For asynchronous operations like docker compose up, the system employs a SpinStep.

Data Formatting and Layout

Table Rendering

The TUI includes a structured table system that supports headers, styled rows, and bordered layouts. It is extensively used for status, ports, and volumes commands.

• Styling: Tables use functional styling, allowing different colors for specific columns (e.g., green for "RUNNING" state, yellow for "PAUSED").
• Truncation: Long strings (like instance names or paths) are truncated with an ellipsis (…) to maintain table alignment.

Sources: internal/cli/render.go:231-250, internal/cli/render.go:605-613

Specialized Result Formatting

The system implements specific rendering logic for various command results:

• Init Proposals: Uses a YAML-like structure to show proposed docktree.yml configurations with "TODO" comments for user decisions.
• Validation Results: Highlights errors with a red ✗ and warnings with a yellow ⚠.
• Port Assignments: Renders container-to-host mappings with arrow symbols: 8080 → 41001.

Sources: internal/cli/init.go:138-144, internal/cli/render.go:117-133, internal/cli/render.go:154-159

Structured Documentation (HelpDocs)

Documentation is treated as a data structure (HelpDoc), enabling it to be rendered as formatted text for users or JSON for tools.

type HelpDoc struct {
	Command     string       `json:"command"`
	Synopsis    string       `json:"synopsis,omitempty"`
	Usage       []string     `json:"usage,omitempty"`
	Options     []HelpOption `json:"options,omitempty"`
	Subcommands []HelpCmd    `json:"subcommands,omitempty"`
	Examples    []string     `json:"examples,omitempty"`
}

Sources: internal/cli/help_doc.go:12-23

This structure allows the renderHelpText function to delegate rendering to legacy text printers while still supporting modern JSON inspection of CLI capabilities via docktree help --json.

Sources: internal/cli/help_doc.go:58-69

Summary

The Docktree UI and Formatting system bridges the gap between complex infrastructure operations and developer productivity. By combining low-level terminal control (ANSI escapes, width detection) with high-level data modeling (HelpDocs, Render Results), it ensures that information is accessible whether being read by a human developer or a machine-learning agent. Key components like the StepPrinter and the dual-mode humanRenderer provide the necessary feedback loops for managing isolated Docker environments across git worktrees.