Inspection Commands (status, ports, volumes)

Relevant source files

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

• internal/cli/render.go
• internal/cli/help_doc.go
• internal/docker/cleanup.go
• skills/docktree/SKILL.md
• CONTRIBUTING.md

Inspection commands in Docktree provide developers with real-time visibility into the state of Docker Compose services, network port mappings, and persistent volumes across multiple git worktrees. These commands are essential for discovering active environments and troubleshooting connectivity or storage issues in isolated worktree projects.

The system supports both human-readable TUI output and machine-readable JSON formats, allowing for easy integration with terminal workflows and automated scripts. By querying the local state and Docker daemon labels, Docktree presents a unified view of managed resources.

Sources: skills/docktree/SKILL.md, internal/cli/render.go:210-213

Command Architecture and Data Flow

Inspection commands follow a pattern of retrieving state from two primary sources: the Docktree state directory and the Docker daemon via label filters.

Docktree uses labels such as docktree.managed=true and docktree.instance to identify resources belonging to specific worktree projects.

Sources: internal/docker/cleanup.go:23-28, internal/cli/render.go:7-12

Status Command

The status command provides a comprehensive overview of managed services within a worktree. It displays service states (running, paused, stopped), image names, and current health status.

Status Logic

• Local Context: By default, it shows the status of the current worktree's instance.
• Global Context: Using the -a or --all flag, it aggregates the status of all worktree instances found in the global state.
• Service Breakdown: It unmarshals data from compose ps --format json to determine exactly how many services are running versus the total count.

Status Indicators

Icon/Badge	Meaning	Description
● RUNNING	Active	All services are in the "running" state.
◌ PAUSED	Suspended	All services are currently paused.
● PARTIAL	Mixed	Some services are running while others are stopped or exiting.
○ STOPPED	Inactive	No containers are currently active for the instance.

Sources: internal/cli/render.go:215-280, internal/cli/help_doc.go:167-178

Ports Command

The ports command maps internal container ports to the dynamically allocated host ports. This is critical because Docktree randomizes host ports to prevent collisions between different worktrees.

Port Mapping Details

When rendered, the command provides the following information:

1. Service: The name of the service defined in the compose file.
2. Container Port: The internal port used by the application.
3. Host Port: The high-range port allocated on the host machine.
4. URL: A clickable link (e.g., http://127.0.0.1:41234) for direct browser access.

Volumes Command

The volumes command inspects Docktree-managed Docker volumes. It filters volumes based on the com.docker.compose.project or docktree.instance labels.

Volume Metadata

The command retrieves and displays:

• Volume Name: The local name used within the Compose file.
• Docker Name: The actual unique name assigned by the Docker daemon (usually prefixed with the instance name).
• Driver: The storage driver used (e.g., local).

Sources: internal/docker/cleanup.go:134-170, internal/cli/render.go:397-440

Output Formats

Docktree supports two primary output modes to satisfy different usage requirements.

Human-Readable (TUI)

The human renderer uses the internal/tui package to create styled, bordered tables. It calculates terminal width to ensure proper alignment and uses color coding (Green for OK, Yellow for Warning, Red for Error).
Sources: internal/cli/render.go:15-25

Machine-Readable (JSON)

When the --json flag is used, Docktree suppresses progress UI (sending it to stderr) and writes a single JSON object to stdout.

{
  "instance": "docktree-main",
  "entries": [
    {
      "service": "web",
      "container_port": 80,
      "host_port": 41002,
      "host_ip": "127.0.0.1"
    }
  ]
}

Sources: skills/docktree/SKILL.md, internal/cli/help_doc.go:39-44

Summary

The inspection commands form the observational core of Docktree. By abstracting the complexity of dynamic port ranges and prefixed resource names, they allow developers to interact with multiple git worktrees as if each were an isolated, standard Docker Compose environment. The ability to toggle between local and global views (--all) provides the necessary context for managing large-scale, multi-branch development projects.