Billar-specific guidance for creating CLI command outputs with the canonical DTO, formatter strategy, and text override pattern. Trigger: when adding or reviewing command output models, CLI output formatting, text views, or new output-bearing commands in this repo.
architecture-billar for broader layer ownership and package boundaries.golang-patterns for general Go implementation, seams, and tests.internal/core.internal/app; output translation belongs in internal/connectors.json and toon must serialize the same canonical DTO.text may use an optional custom text override when the generic fallback is not clear enough.TextWriter override.| Format | Purpose | Source of truth |
|---|---|---|
text | Human-first CLI output | Custom TextWriter or generic text fallback |
json | Stable machine-readable output | Canonical payload |
toon | Tag-based structured output | Canonical payload with toon tags |
Use generic text fallback when:
name: value is already readable enough.Provide custom text when:
json and toon share them.json and toon tags on structured output fields.text rendering for the human view.Makefile for normal repo commands, but do not assume one make target per output format.text, json, and toon.toon output only works predictably when DTO fields include explicit toon tags.json and toon should stay aligned through the same canonical payload.type StatusDTO struct {
Name string `json:"name" toon:"name"`
Status string `json:"status" toon:"status"`
}
result := cli.OutputResult{
Payload: StatusDTO{Name: "billar", Status: "ok"},
TextWriter: func(w io.Writer) error {
_, err := io.WriteString(w, "Billar Health\n")
return err
},
}
make test
make fmt
make run-health
internal/connectors/cli/output.gointernal/app/health_service.godocs/technical_blueprint.md