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: MIT5compatibility: Codex, Claude Code, and other Agent Skills-compatible clients.6metadata:7 version: "0.2.0"8 displayName: Go CLI Terminal Experience9 category: Go10 tags: go,golang,cli,terminal,tty,accessibility,agents11---1213# Go CLI Terminal Experience1415Make interaction an explicit mode, not an accidental consequence of where the16process runs. Preserve stable data and failure contracts underneath rich output.1718## Core Workflow19201. Identify the caller and choose `human`, `plain`, or `structured` mode.212. Detect terminal capabilities separately for stdin, stdout, and stderr.223. Define stable stdout data, stderr diagnostics, and noninteractive behavior.234. Add color, prompts, progress, or a dashboard only in compatible modes.245. Propagate cancellation and treat a downstream closed pipe as normal completion.256. Test terminals, redirection, CI, agents, accessibility controls, and interruption.2627## Read Next2829| Task | Load |30|---|---|31| Choose output and interaction modes | `guidelines.md`, `workflows/design-output-modes.md` |32| Add prompts, progress, color, or secrets | `references/terminal-experience/rules.md`, `workflows/add-safe-interaction.md` |33| Build a full-screen terminal UI | `workflows/build-terminal-dashboard.md` |34| Review examples and edge cases | `references/terminal-experience/examples.md` |35| Understand capability detection | `references/terminal-experience/knowledge.md` |3637## Guardrails3839- Never prompt, animate, or emit ANSI control sequences in structured mode.40- Do not infer stdin capability from stdout; inspect each stream independently.41- Honor explicit flags first, then environment conventions such as `NO_COLOR`,42 then terminal detection.43- Keep secrets out of arguments, history, logs, errors, and diagnostic bundles.44- Make `Ctrl-C`, context cancellation, and broken pipes deterministic.4546## Source Notes4748Guidance is transformed and paraphrased from Marian Montagnino,49*Building Modern CLI Applications in Go* (Packt, 2023), especially Chapters 850and 10, and Ricardo Gerardi, *Powerful Command-Line Applications in Go*51(Pragmatic Bookshelf, 2021). Examples are original adaptations.5253Verify current APIs against https://pkg.go.dev/golang.org/x/term,54https://no-color.org/, and the selected terminal UI framework.5556Renderer lifecycle and backpressure guidance also incorporates transformed57material from Inanc Gumus, *Go by Example: Programmer's Guide to Idiomatic and58Testable Programs* (Manning, 2025), Chapters 6-7.
LVTD-LLC