go-cli-terminal-experience

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

1. Identify the caller and choose human, plain, or structured mode.
2. Detect terminal capabilities separately for stdin, stdout, and stderr.
3. Define stable stdout data, stderr diagnostics, and noninteractive behavior.
4. Add color, prompts, progress, or a dashboard only in compatible modes.
5. Propagate cancellation and treat a downstream closed pipe as normal completion.
6. 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.