# 0118. Human output by default; YAML and JSON on request

Status: Accepted · Date: 2026-11-04 · Design section: CLI and UI · Touches: 0014, 0117

Decided: `ichor` prints for a person unless `-o yaml` or `-o json` is given: a table or an aligned key/value block, enum names without their type prefix (`control-plane`, not `MACHINE_ROLE_CONTROL_PLANE`), the glyphs ✓ ! ✗ … for status and ages like `5m`, with colour only on a terminal (`NO_COLOR` and `TERM=dumb` honoured, the layout identical in a pipe). The global `-o` defaults to unset instead of `yaml`. `-o yaml` and `-o json` print exactly what they printed before, so scripts opt in by naming the format. A command with no human view yet prints YAML when `-o` is unset (`machineFormat`, used by every writer of a machine format), so nothing prints nothing; every command that reports a result has a human view now, and `ichor ui` prints its status lines in the same style; what streams or prints raw content (`node logs`, `cni values get`, the `auth` credential plugin) stays as it is. The shared helpers are in `internal/cli/human.go`. `Cluster` and `Machine` in the Connect API gain `created_at` (for the AGE column) and `Cluster` gains `endpoint_type`, `pod_subnets`, `service_subnets` and `cni_tunnel`, so `cluster get` can show them.

## Context

Every command dumped YAML by default, including the protobuf enum names (`MACHINE_APPROVAL_STATE_APPROVED`). `ichor init` already shows its steps as a short list with glyphs and a spinner (progress.go); the rest of the CLI should read the same way. Other agents convert the remaining commands, so the foundation has to be easy to reuse.

## Decision

1. `-o` is unset by default. `validateOutputFormat` accepts unset, `yaml` and `json`. `machineFormat("")` is `yaml`; `writeMessage`, `writeOutput` and `writeOutputObjects` go through it, so an unconverted command keeps its YAML.
2. A converted command prints through `showAPIHuman` (or `printAPI`) with a render function. The render function is used only when `-o` is unset; otherwise the wire message is printed as ever. Commands whose old output was not the wire message (`cluster status` printed `key: value` lines whatever `-o` was) keep that text for `-o yaml|json`.
3. The helpers reuse progress.go's terminal detection and SGR constants: `human.Table`, `human.Block`, `human.Title`/`Line`, `human.Conditions`, `human.Mark`, `humanEnum`, `humanAge`, `humanUntil`, `conditionMark`, `shortNames`. Tables are our own column layout, not `text/tabwriter`, because tabwriter counts the bytes of a colour code as width and misaligns coloured cells. Nothing is truncated: a long cell stays whole in a pipe and on a terminal.
4. A machine's name is shortened to its first eight characters only when that stays unique in the listing; otherwise it is printed in full. `get` always prints the full name.
5. `humanEnum` strips an enum's type prefix by looking the value up in the compiled-in protobuf descriptors, so it needs no per-enum table.
6. Condition glyphs know the polarity of Ichor's condition types (`ConfigWarnings` True is `!`, `Ready` False is `✗`, `Transitioning` True is `…`).

## Consequences

- A script that read the default output must now say `-o yaml`. The CLI's own docs and guides do.
- `-o yaml|json` of `cluster list|get` and `machine list|get` carry the new fields (`createdAt`, `endpointType`, `podSubnets`, `serviceSubnets`, `cniTunnel`); fields are only added, and a CLI that talks to an older ichor-ui shows `-` for an age it does not have.
- A command with a human view is a render function passed to `showAPIHuman` or `printAPI`; a start command (`upgrade`, `cni kube-proxy`, `config apply`, the node actions, `restore --live`) goes through `runStartOperation`, `runNodeAction` and `watchOperation`, which print the result and the live view.