Go CLI Terminal Experience
Make interaction an explicit mode, not an accidental consequence of where the
process runs. Preserve stable data and failure contracts underneath rich output.
Core Workflow
- Identify the caller and choose
human, plain, or structured mode.
- Detect terminal capabilities separately for stdin, stdout, and stderr.
- Define stable stdout data, stderr diagnostics, and noninteractive behavior.
- Add color, prompts, progress, or a dashboard only in compatible modes.
- Propagate cancellation and treat a downstream closed pipe as normal completion.
- Test terminals, redirection, CI, agents, accessibility controls, and interruption.
Read Next
| Task |
Load |
| Choose output and interaction modes |
guidelines.md, workflows/design-output-modes.md |
| Add prompts, progress, color, or secrets |
references/terminal-experience/rules.md, workflows/add-safe-interaction.md |
| Build a full-screen terminal UI |
workflows/build-terminal-dashboard.md |
| Review examples and edge cases |
references/terminal-experience/examples.md |
| Understand capability detection |
references/terminal-experience/knowledge.md |
Guardrails
- Never prompt, animate, or emit ANSI control sequences in structured mode.
- Do not infer stdin capability from stdout; inspect each stream independently.
- Honor explicit flags first, then environment conventions such as
NO_COLOR,
then terminal detection.
- Keep secrets out of arguments, history, logs, errors, and diagnostic bundles.
- Make
Ctrl-C, context cancellation, and broken pipes deterministic.
Source Notes
Guidance is transformed and paraphrased from Marian Montagnino,
Building Modern CLI Applications in Go (Packt, 2023), especially Chapters 8
and 10, and Ricardo Gerardi, Powerful Command-Line Applications in Go
(Pragmatic Bookshelf, 2021). Examples are original adaptations.
Verify current APIs against https://pkg.go.dev/golang.org/x/term,
https://no-color.org/, and the selected terminal UI framework.
Renderer lifecycle and backpressure guidance also incorporates transformed
material from Inanc Gumus, Go by Example: Programmer's Guide to Idiomatic and
Testable Programs (Manning, 2025), Chapters 6-7.
1---2name: go-cli-terminal-experience3description: Design and review adaptive Go CLI terminal experiences with explicit human, plain, and structured modes; per-stream TTY detection; color and accessibility controls; prompts; progress; secret input; cancellation; and broken-pipe handling. Use when a Go CLI must work safely for people, scripts, AI agents, CI, redirected streams, or interactive dashboards.4license: MIT5---67# Go CLI Terminal Experience89Make interaction an explicit mode, not an accidental consequence of where the10process runs. Preserve stable data and failure contracts underneath rich output.1112## Core Workflow13141. Identify the caller and choose `human`, `plain`, or `structured` mode.152. Detect terminal capabilities separately for stdin, stdout, and stderr.163. Define stable stdout data, stderr diagnostics, and noninteractive behavior.174. Add color, prompts, progress, or a dashboard only in compatible modes.185. Propagate cancellation and treat a downstream closed pipe as normal completion.196. Test terminals, redirection, CI, agents, accessibility controls, and interruption.2021## Read Next2223| Task | Load |24|---|---|25| Choose output and interaction modes | `guidelines.md`, `workflows/design-output-modes.md` |26| Add prompts, progress, color, or secrets | `references/terminal-experience/rules.md`, `workflows/add-safe-interaction.md` |27| Build a full-screen terminal UI | `workflows/build-terminal-dashboard.md` |28| Review examples and edge cases | `references/terminal-experience/examples.md` |29| Understand capability detection | `references/terminal-experience/knowledge.md` |3031## Guardrails3233- Never prompt, animate, or emit ANSI control sequences in structured mode.34- Do not infer stdin capability from stdout; inspect each stream independently.35- Honor explicit flags first, then environment conventions such as `NO_COLOR`,36 then terminal detection.37- Keep secrets out of arguments, history, logs, errors, and diagnostic bundles.38- Make `Ctrl-C`, context cancellation, and broken pipes deterministic.3940## Source Notes4142Guidance is transformed and paraphrased from Marian Montagnino,43*Building Modern CLI Applications in Go* (Packt, 2023), especially Chapters 844and 10, and Ricardo Gerardi, *Powerful Command-Line Applications in Go*45(Pragmatic Bookshelf, 2021). Examples are original adaptations.4647Verify current APIs against https://pkg.go.dev/golang.org/x/term,48https://no-color.org/, and the selected terminal UI framework.4950Renderer lifecycle and backpressure guidance also incorporates transformed51material from Inanc Gumus, *Go by Example: Programmer's Guide to Idiomatic and52Testable Programs* (Manning, 2025), Chapters 6-7.
LVTD-LLC