JSON Mode for Machines

Relevant source files

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

• internal/cli/render.go
• internal/cli/types.go
• internal/cli/help_doc.go
• internal/cli/json_render_test.go
• skills/docktree/SKILL.md
• internal/cli/init.go

JSON Mode for Machines is a global feature in Docktree that provides structured, machine-readable output for integration with scripts, AI agents, and other automated systems. By using the --json flag, Docktree bypasses its human-friendly Terminal User Interface (TUI) and emits single, valid JSON objects to stdout.

This mode covers two primary categories of interaction: Native Commands, which produce comprehensive status and result objects, and Help/Version queries, which return structured documentation and metadata. While human-readable logs and Docker Compose progress are directed to stderr, stdout remains reserved for the machine-readable payload.

Sources: skills/docktree/SKILL.md:21-30, internal/cli/help_doc.go:12-25

Global Activation and Architecture

JSON mode is activated by passing the --json global flag before any subcommand. The system architecture separates the data acquisition logic from the rendering logic. Native commands return a result object which is then passed to a generic renderer. If JSON mode is enabled, the system uses a JSON encoder to serialize the result; otherwise, it passes the data to a humanRenderer function for terminal-formatted output.

Execution Flow for JSON Output

The following diagram illustrates how a command request is processed and rendered as JSON:

A brief explanation: The CLI detects the global --json flag during context initialization. Commands return structured data (e.g., UpResult, StatusResult) which the renderer converts to JSON or TUI-styled text based on that context.

Sources: internal/cli/render.go:21-30, skills/docktree/SKILL.md:21-25, internal/cli/types.go:15-21

Structured Result Types

Native commands in Docktree are mapped to specific Go structures that define the JSON schema for that command's output.

Key Result Structures

Command	Result Structure	Key Fields
up	UpResult	instance, ports, services, shared_services, hint
status	StatusResult	instance, raw, stopped
ports	PortsResult	all, entries (instance + port assignments)
init	InitResult	written, todos, warnings
clean	CleanResult	dry_run, instances, totals

Sources: internal/cli/types.go:23-145, internal/cli/init.go:343-348

Initialization and AI Integration (init)

The init command uses JSON mode to communicate required configuration decisions to AI agents. It emits InitTodo objects containing paths to YAML fields, questions, and available options (enums).

{
  "path": "shared.services.db.tenancy",
  "question": "Service \"db\" looks like postgres. Should it run in the shared platform tier...?",
  "kind": "enum",
  "options": ["full_share", "per_database"]
}

Sources: internal/cli/init.go:261-270, internal/cli/types.go:195-201

Docker Compose Passthrough

For commands that act as direct wrappers for docker compose (e.g., logs, ps, exec), Docktree does not wrap the output in its own JSON structure. Instead, users must pass Docker's native formatting flags.

Error Handling

When an error occurs in JSON mode (or when stdout is a non-TTY), Docktree emits a structured error object and exits with a specific code.

Error Object Schema

• error: A short string code representing the error category.
• message: A human-readable description of the error.
• details: Optional additional context (e.g., specific validation failures).

Exit Codes

Code	Label	Description
0	OK	Command completed successfully.
2	Usage	Argument parsing or usage error.
3	Config	Error in docktree.yml or git environment.
4	Docker	Failure communicating with the Docker daemon.
5	Noop	Command had no work to perform.
6	Conflict	Resource conflict (e.g., port registry lock).

Sources: skills/docktree/SKILL.md:65-71, internal/cli/render.go:610-625

Structured Documentation (Help/Version)

JSON mode allows for the programmatic retrieval of command documentation. The HelpDoc structure provides a complete schema of usage, flags, and examples.

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"`
}

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

Summary

JSON Mode for Machines is a critical architectural layer in Docktree that enables integration with automated environments. By providing deterministic JSON schemas for all native commands and leveraging Docker's native formatting for passthrough commands, it ensures that Docktree can serve as a reliable component in CI/CD pipelines and agentic workflows.

Sources: skills/docktree/SKILL.md:73-100