Skip to content
SHC Docs

Output & messaging contract

Layer 4. Primitives. Primitives

Status: Normative as of 2026-07-02. This is the single contract for every user-facing string SHC produces: CLI output, streamed progress, errors, warnings, prompts, daemon logs, notifications, help text, and HUD labels. It supersedes the output sections of docs/reference/cli/overview.md (rewritten against this doc) and wins over any older description of output behavior. Enforcement is listed in §15; drift against this doc is a defect, not a preference.

Why it exists: an audit of the live CLI (2026-07-02) found five competing output grammars across four adjacent commands: raw JSON dumps, compose-style spinner blocks, key=value lines carrying prose, headerless hand-padded pseudo-tables, and duplicated error lines in two formats. Every grammar was locally reasonable; nothing owned the whole. This doc owns the whole.


  1. One grammar per situation. A situation (a list, a mutation result, a warning, a failure) has exactly one output shape, produced by exactly one shared helper. Commands never hand-roll a shape a helper exists for.
  2. stdout is data, stderr is chrome. Already normative in core/render/streams.go; restated here because every rule below hangs off it.
  3. Say it once. No fact or error appears twice in one invocation.
  4. Human words for humans, structure for machines. tty/text modes speak plain sentences; -o json/-o yaml carry the structure. key=value is not a human grammar and is retired from tty/text output.
  5. No internal vocabulary in user-facing strings. No field names (stack_name), no mechanism narration (“backfilled by reconcile”), no plan/phase codenames. Users see product nouns (§11) only.

render.Streams(mode, stdout, stderr) is the only way a command resolves its writers. Data (tables, documents, result lines) → data writer. Chrome (progress, warnings, prompts, the text-mode error line) → chrome writer. The data writer is stdout and the chrome writer is stderr, in every mode. Under structured modes stdout carries exactly one parsable document, and a failed command’s coded error envelope is that document. No direct os.Stdout/os.Stderr writes in command code.

  • The global -o, --output flag owns format selection: tty | text | json | yaml. Default: tty when stdout is a terminal, text when piped.
  • Commands MUST NOT re-register --output/-o, add --json booleans, or spell format as --format. (66 local re-registrations existed at audit time; they also shadowed global shorthands; see §10.)
  • All four modes work on every command. A command never “supports only json|text”: structured rendering is free via the SmartFormatter (core/render), which also provides --fields/--filter/--exclude.
  • NO_COLOR (and non-tty stdout) disables ANSI everywhere, including render.FormatValueTTY and YAML highlighting, not just lipgloss surfaces.
  • Lists render through render.Print → column table: UPPER_SNAKE headers, two-space gutter, empty columns dropped, width-fitted. No hand-rolled tabwriter/%-32s tables, no headerless lists, no lowercase headers.
  • Empty list: exactly no <plural-noun> on the data writer (e.g. no backups), dim in tty. Not silence, not a bare header row, not exit 1.
  • A list under -o json or -o yaml is a bare array of its rows, [] when empty: shc ls, shc node ls, shc backup ls and every other ls. No {"message": …}, {"nodes": …} or {"rows": …} around it. That {"message": …} is the daemon API’s method envelope, which a client of /api/method/… reads and the CLI unwraps. An ls that prints one document rather than rows (shc retention ls’s policy, shc dns ls’s inventory) is named with its reason in cmd/shc/list_json_shape_test.go, which holds every other ls to the rule.
  • A graph is a document, not a list. shc integration graph prints Graphviz DOT in tty and text mode, so a pipe into dot draws it, and an empty scope prints digraph shc {}, not no deployments: nothing on stderr, exit 0. -o json and -o yaml carry the same graph as data (SHC-3344).
  • Details (one object) render as the SmartFormatter’s flat-fields + nested-boxes shape.
  • Markers: an “active/current” row is marked in a dedicated leading column with *. A marker that no data path can ever set is a defect (dead affordance), not a feature.

One line on the data writer, grammar:

<verb-past> <noun> "<name>"[, <short fact>[, <short fact>]]

Examples: installed deployment "plane" · created tenant "test", switched · removed node "node-3" · rotated cluster CA, generation 4.

  • Lowercase, no trailing period, names in double quotes. No parenthesis: a fact is a comma clause of the sentence, or its own column, never an aside.
  • The line opens with ✔ in tty and in text mode alike, green in tty. A pipe gets exactly what the terminal settles on, less its color and its animation, so a block captured from either is true for both (SHC-2468). A script reads -o json, never the sentence.
  • -o json/yaml render the full result object instead; the sentence is tty/text only.
warning: <lowercase message>
  • Chrome writer. Yellow in tty (color only; same text every mode).
  • Coded warnings (X2xxxxx) include the code: warning [X200912…]: <message>.
  • One helper. The four shapes found at audit time (warning=, warning:, stdout vs stderr, bare prose) are all this one now.
  • Warnings crossing HTTP (204 + X-SHC-Warning-Code) are read by the client and re-emitted through the same helper, never silently dropped.

A successful command prints its result and nothing else. No hint line follows a success or an ordinary empty list.

  • A warning (§5) is printed only when something is wrong or will go wrong.
  • A refusal names its fix in the error line (§7).
  • Every “run this next” remediation (in warnings and error templates) uses backticks around the command. No unquoted run shc x.
  • Exactly one error line per failure. The canonical render is renderRunError: shc: [X…CODE] message on the chrome writer (text/tty), or the coded envelope as part of the stdout document (json/yaml).
  • The remedy is a clause of that line. A refusal names its fix once: shc: [X…CODE] message, <remedy>. A remedy the message already says is not repeated, and no hint line follows a failure.
  • A streamed operation that already rendered ✘ <detail> inline returns its error wrapped to satisfy SilentExit() bool, so the top-level line is suppressed. The double-print (inline row + shc: line) is a defect. Its remedy, when it has one, is one plain sentence under the row.
  • Exit codes: usage/parse errors → 2; every runtime failure → 1. A *coded.CodedError is by definition runtime; it short-circuits the usage-error heuristics. (The old errors.md claim “4xx→1, 5xx→2” is retired; the 4xx/5xx class travels in the JSON envelope for scripts.)
  • Message style (enforced by arch-fitness check 8, extended): lowercase, single flat clause, no colons/semicolons/parens, no trailing period. Include the scope that disambiguates the failure; a not-found in a scoped namespace names the tenant and environment searched.
  • One code, one meaning: a code is never minted with a second message template (full-string collisions are defects; numeric-prefix collisions are ratcheted).

8. Progress of a long-running command (install/update/uninstall/recover/init/…)

Section titled “8. Progress of a long-running command (install/update/uninstall/recover/init/…)”

Every long-running command shows its progress through one display (SHC-2468). core/progress decides how it shows: live on a terminal (tty mode, stdout and stderr both terminals), plain off one, nothing under -q. The multiplexed operation renderer (operation_live) is the only spinner grammar and holds the one model of blocks and rows; the plain renderer (operation_plain) prints from that same model. A command that animates a spinner, moves the cursor, starts a live line, builds a renderer or prints a <verb>ing … line of its own is a defect, and the core/progress/ownerscan tests fail on one.

  • A pipe gets exactly what the terminal settles on, less its color and its animation. The frame a terminal ends on and the lines a pipe prints are one text, line for line: a block captured from either is true for both.
  • Announce line (chrome, before the display): <verb-ing> <noun> "<name>": installing deployment "plane", installing modules postgres, keycloak, traefik for tenant "master". Lowercase; same grammar for single and system installs.
  • Live row of one request: a command that waits on one request and follows no operation (join, leave, drain, clone, restore) shows one row, spinner, what it does, seconds waited: ⠙ join the cluster 4s. It is erased when the wait ends and leaves nothing behind; the result line says it. The same row stands in for an operation until its first block draws.
  • Block header: [<deployment>] <State> <done>/<total>, always the name, never a literal [+]. State words: Starting, Running, Healthy, Complete, Failed, Degraded (vocabulary per status-states.md). A failure before anything deployed is Failed, never Degraded. A block draws once it has a row or the daemon has said how many it will have; never a bare Starting 0/0.
  • Rows: <mark> <service> <status>[ <duration>] for a service and <mark> <what the step does> for a step, with marks: spinner (in flight), ✔ (settled), ✘ (failed), - (not run / cut short). A step’s words are the step frame’s own message, written once by the daemon in lowercase with no name in it (remove from far01, take the safety backup): the row and the pipe’s line cannot differ. Rows come from the operation’s own frames, its steps and its deployment snapshots, never from bus status events, which reach a follower on some runs and not on others. A step turns ✔ when the next one starts, unless it ends on its own: each deployment of a backup fire does, since the fire goes on past one that fails. Such a step’s end is a frame of its own, step done or failed with the step’s words, and a step run again (a retried deployment) is the same row, moved last.
  • Convergence is mandatory: the final frame of a successful operation shows every row ✔ and the header count complete; the final frame of a failed one shows the failing row ✘, in-flight rows frozen to - (never a stale animation frame), and never promotes an unfinished row to ✔ healthy. A followed verb’s failed row names what failed and the one error line (§7) says why, in full.
  • Off a terminal (pipe, file, CI, -o text, and the chrome of -o json and -o yaml): the same header and rows, printed once per deployment when it settles, in the order the block lists them, so rows that become ready in a different order on each run print the same every run. A notice or a warning prints when it arrives, above the blocks, where a terminal scrolls it. Final line = the result line (§4) or the error.
  • Several deployments at once (shc init’s modules): a block that settles while others still run moves above them on a terminal and stays there, so a terminal and a pipe list the deployments in the order they settled.
  • Every destructive verb (rm, uninstall, purge, rotate, leave, force-moves) prompts: <verb> <noun> "<name>"? [y/N] on the chrome writer.
  • --yes/-y skips the prompt. A registered --yes that is parsed and discarded is a defect (four existed at audit).
  • Decline prints aborted (chrome) and exits 1, never a silent exit 0.
  • Non-tty stdin without --yes refuses loudly with a coded error naming the flag, never silently proceeds, never silently exits 0.
  • Unknown subcommands under a group are errors (cobra NoArgs/unknown-command error), not exit-0 help and never fall-through into the group’s default action.
  • Short: lowercase imperative verb phrase, no trailing period, ≤ 60 chars. Same casing on every command (9 capitalized outliers at audit).
  • Long: required for any command with > 6 flags, destructive semantics, or async behavior. Sentences, wrapped at 80.
  • Example: required for the flag-heavy verbs (update, backup create/restore, recover, clone, install at minimum).
  • Flags: kebab-case long names. Never re-register a global flag name locally (it silently destroys the inherited shorthand; backup create -e broke this way). Never document a shorthand that isn’t registered. One concept = one long name across the tree (--tail, not --tail here and --lines there).
  • Scope ladders in help text use ADR-0003 vocabulary verbatim: global|tenant|environment|stack|deployment.
  • List verbs: ls is canonical; list is a cobra Aliases entry, not a second registered command. ps exists only where it means processes/runs, and never as a synonym of ls in the same family.
  • Nouns (user-facing): deployment (the running unit), stack (the app-identity axis: -s/--stack and the scope path), app (catalog entry), tenant, environment, node, cluster, backup, volume, connection, secret, certificate. The HUD, CLI, API messages, and docs use the same noun for the same thing.
  • Status words: exactly the sets in docs/architecture/status-states.md (including paused and unknown). One Go source of truth for status buckets; duplicated bucket maps are defects.
  • Names are double-quoted in prose (results, announces, warnings). Error templates converge opportunistically (no mass rewrite).
  • Banned in user-facing strings and logs: internal field names, plan/ phase codenames, mechanism narration. Real X-codes and issue numbers are fine.
  • core/log (corelog) is the only logging API. No fmt.Fprintf(os.Stderr, …) in daemon/subsystem/api code (breaks SHC_LOG_FORMAT=json, skips redaction and the OTel bridge); no stdlib log.Printf (the two core/config import-cycle sites get an injected logger seam).
  • The CLI calls corelog.Init too; redaction and SHC_LOG_FORMAT apply to every process, not just the daemon.
  • Keys: the Field* constants are the schema; the error value is always error, node identity is always node_id. New concepts get a constant before first use.
  • Levels: Error = failed and needs an operator; Warn = degraded, retrying, or unexpected-but-continuing; Info = lifecycle milestones; Debug = diagnosis detail. A reconcile/renewal/materialize FAILURE is never Debug.
  • Operator-actionable Warn/Error carries an X-code (typed corelog call) so it reaches the event bus and notifier; untyped .Warn/.Error on injected loggers is a bypass, not a second tier.
  • Message style: lowercase, no trailing period, no ALL-CAPS.
  • Notification content uses the same vocabulary (§11) and status words, and carries the X-code of the event that triggered it.
  • The delivery pipeline must be real: a rule engine whose dispatcher never starts (the audit state) is treated as a broken contract, not a todo; wiring the worker pool and the shc notification test daemon round-trip are part of this contract’s remediation.
  • Config-reload keys match both the bare notifications key and dotted notifications.* prefixes.
  • Status words, nouns, and buckets come from the same sources as §11; the HUD never maintains a private status taxonomy.
  • Every advertised affordance works where it is advertised: an action chip shown on a row must have a handler for that view; the help overlay lists only actions that work in the HUD and labels CLI-redirects as such; hint text names the real keybinding (ctrl+r, not r).
  • Toasts/flash lines only for errors; passive indicators for everything else (existing house rule, already honored).

Added to scripts/arch-fitness.sh (ratchets unless noted):

  1. no-local-output-flag: re-registrations of --output/-o, --json bools, format---format flags outside the CLI root: ratchet → 0.
  2. daemon-stderr-ban: fmt.Fprint*(os.Stderr under daemon, subsystems (the ce daemon/subsystems trees carry the rule in the ce publish flow): ratchet → 0.
  3. template-style: check 8 extended: semicolons banned in message templates alongside colons/parens/trailing periods.
  4. key-value-output-ban: key=value Fprintf patterns in command RunE paths: ratchet → 0 as migration lands.
  5. shorthand-shadow: flag_shorthand_test.go extended to fail when a local flag shadows an inherited global’s shorthand (hard test, not ratchet).
  6. example-floor: cobra Example: count must not decrease once the top-verb examples land.

Everything not enforceable mechanically is enforced by this doc + review.

  • core/render/streams.go: streams discipline (normative code).
  • core/render: SmartFormatter, tables, modes.
  • core/log: field constants, typed emission, redaction.
  • docs/architecture/status-states.md: status vocabulary.
  • docs/decisions/ADR-0003-one-scope-type.md: scope-tier vocabulary.
  • docs/reference/errors.md: code registry (regenerated; exit-code section updated by this contract).
  • Audit evidence: docs/reviews/2026-07-02-output-voice-audit.md.