Billar Command Output

Allowed formats

Text fallback vs custom text

Use generic text fallback when:

• The payload is a simple scalar.
• The payload is a small flat struct or string-keyed map.
• Field-by-field output like name: value is already readable enough.

Provide custom text when:

• The command needs a more human-oriented summary or label.
• Field ordering, wording, grouping, or omission matters for readability.
• The payload is a list, nested structure, or otherwise awkward for the generic fallback.
• The command should present a future table or multi-line view for humans.

Design patterns to keep

• Canonical DTO plus optional text override.
• Formatter strategy selected by output format.
• Small builder/helpers for human text views; keep them boring and connector-local.
• Do not fork separate DTOs per structured format unless there is a real external compatibility need.

Recommended Practices

• Use stable field names for canonical DTOs because json and toon share them.
• Add both json and toon tags on structured output fields.
• Keep DTOs simple, explicit, and easy to serialize.
• Prefer flat DTOs first; only add nesting when it materially improves the contract.
• Treat canonical payloads as the long-lived contract for machine-readable output.
• Keep fallback text simple; do not turn it into a mini rendering framework.
• For future list or table commands, keep the canonical payload machine-friendly and add custom text rendering for the human view.
• Follow the Makefile for normal repo commands, but do not assume one make target per output format.

Key Learnings

• Billar currently supports exactly 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.
• The generic text fallback is intentionally narrow and should remain simple.
• The current output strategy and small text builder are enough for now; extend them incrementally instead of introducing a larger rendering abstraction.

Minimal Example

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
    },
}

Commands

make test
make fmt
make run-health

Resources

• Output formatter path: internal/connectors/cli/output.go
• Example DTO: internal/app/health_service.go
• Primary source: docs/technical_blueprint.md