CLI Architecture and Options

Relevant source files

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

• internal/cli/cli.go
• internal/cli/help_doc.go
• internal/cli/render.go
• internal/cli/up.go
• internal/cli/init.go
• internal/cli/worktree.go
• internal/config/config.go

Introduction

The Docktree CLI is a Go-based tool designed to coordinate Docker Compose services across multiple git worktrees. It provides an abstraction layer over standard Docker Compose commands, ensuring that each worktree operates within an isolated environment with unique port allocations, container names, and volumes to prevent resource collisions.

The architecture is built around a centralized command execution engine that handles global flags (such as --json), command routing, and specialized rendering for both human-readable terminal output and machine-readable JSON formats. This design enables Docktree to be "agent-native," facilitating seamless integration with AI coding agents and automated workflows.
Sources: internal/cli/cli.go:1-20, README.md:1-15

Command Execution Flow

The CLI entry point processes arguments by first extracting global flags and then dispatching the command to a specific handler.

Execution Lifecycle

1. Parsing Global Flags: The system checks for the --json flag to determine the output mode.
2. Context Creation: A Context object is initialized, containing arguments, the selected renderer, and standard I/O streams.
3. Command Routing: The runRootCommand function matches the input against a rootCommands map.
4. Progress Tracking: For long-running operations like up or down, a progress printer is optionally attached to stderr if the output is a TTY.
5. Rendering: The result of the command (or an error) is passed to the Renderer, which applies either a humanRenderer or a JSON encoder.

This flow is illustrated in the following diagram:

The diagram shows the sequence from initial input to the final rendering of results.
Sources: internal/cli/cli.go:49-106, internal/cli/cli.go:121-140

Core Command Architecture

Docktree categorizes commands into two types: Native commands that return structured Go types for rendering, and Passthrough commands that wrap standard docker compose calls.

Native Command Structure

Native commands return a result object, an exit code, and an error. The result objects are specifically handled by the humanRenderer to provide stylized terminal output.

Command	Purpose	Result Type
up	Starts isolated services for a worktree	UpResult
init	Generates initial docktree.yml	InitResult
status	Shows state of managed services	StatusResult
prepare	Sets up local worktree Docker environment	PrepareResult
clean	Removes stale managed resources	CleanResult

Sources: internal/cli/cli.go:21-47, internal/cli/render.go:21-450, internal/cli/init.go:50-130

Help and Versioning System

Help documentation is managed through a structured HelpDoc type, allowing the CLI to provide consistent documentation in both text and JSON formats.

The structure of the help system ensures that AI agents can programmatically discover CLI capabilities.
Sources: internal/cli/help_doc.go:11-37

Configuration and Options

Docktree's behavior is governed by the docktree.yml file, which is loaded and merged with default values at runtime.

Configuration Model

The Config struct in internal/config/config.go defines the primary settings for the CLI.

Section	Key Fields	Default Value
Worktrees	Root	../${repo}.worktrees
Setup	Copy, Symlink, Run	.env, node_modules
Ports	Mode, Range, BindHost	dynamic, 41000-49999, 127.0.0.1
State	Directory	.docktree

Sources: internal/config/config.go:13-90, internal/config/config.go:93-115

Command-Specific Options

Individual commands have their own option parsing logic to handle specific flags:

• init options: Includes --dry-run, --force, and --apply. Sources: internal/cli/init.go:28-48
• up options: Includes -f/--file, --build, --sync, --validate, and --create <branch>. Sources: internal/cli/help_doc.go:220-238
• down options: Includes -v/--volumes and -a/--all. Sources: internal/cli/help_doc.go:135-150

Output Rendering System

The Renderer in internal/cli/render.go implements the logic for transforming internal result types into user-facing output.

Human-Readable Output

The humanRenderer uses a tui package to provide colored icons (e.g., ✓, ⚠, ●), tables, and accented text. For example, the UpResult renderer displays:

• Project name and sync status.
• Allocated port mappings (e.g., web 80 → 41001).
• Platform services and isolated volumes.
• Environment warnings and stale file notifications.

Machine-Readable Output (JSON)

When --json is active, the human renderer is bypassed. The CLI instead encodes the raw result struct returned by the command handler directly to stdout.
Sources: internal/cli/render.go:26-105, internal/cli/cli.go:68-75

Conclusion

The Docktree CLI architecture is designed for extensibility and interoperability. By separating command logic from output rendering and providing a robust configuration model, it provides a reliable environment for managing Docker Compose in complex git worktree setups, specifically tailored for both human developers and automated agents.