"Rules" that terminal programs follow

Original Article ↗ Hacker News Discussion ↗

Terminal command-line tools are expected to follow a web of informal conventions—like sending data to stdout and human-readable logs to stderr, quitting REPLs on Ctrl‑D, respecting color and keybinding norms, and behaving well in pipes—but many edge cases and historical quirks make this hard to learn and inconsistently applied. Commenters debate whether stderr is best understood as a general “log” stream, how multiple output streams (as in PowerShell) or richer exit codes could improve tooling, and where tilde expansion, globbing, and encoding responsibilities should live (shell vs program vs OS). A recurring theme is the tension between descriptive norms (what most tools already do), prescriptive ideals for better UX and accessibility (e.g., color use, emoji, config locations), and platform differences between Unix-like systems and Windows.

Stdout, Stderr, and a “Stdlog” Concept

  • Strong consensus: program “real output” must go to stdout; anything user-facing but not part of the machine-readable result should go to stderr.
  • Several people argue stderr is better understood as a “log” or “user” stream (errors, warnings, progress, verbose output).
  • This separation keeps pipelines reliable; error/help text in stdout breaks downstream parsing.
  • Some wish for multiple terminal-bound FDs or richer stream models; PowerShell’s multiple streams are cited positively but also criticized as overkill or poorly generalized.

Help, Errors, Exit Codes, and Streams

  • Suggested convention: help/version output goes to stdout when explicitly requested, but to stderr (and leave stdout empty) when invoked due to incorrect usage.
  • Broad agreement that exit codes, not error text parsing, should be the primary way to detect failures.
  • Some mention sysexits.h, though others note most tools just use a few simple exit codes.

Keybindings, REPL Behavior, and TTY Modes

  • Expectation: REPLs quit on Ctrl‑D (Unix) or Ctrl‑Z+Enter (Windows). Some tools (e.g., GHCi in certain environments) violate this, causing confusion.
  • Ctrl‑W deleting the previous word is widely expected; exceptions (e.g., mysql/editline, some browsers/terminals) are seen as frustrating.
  • Explanations of “cooked” vs “raw”/cbreak terminal modes and how they affect Ctrl‑C, Ctrl‑D, line editing, and echoing.

Colors, Emoji, and Accessibility

  • Many want programs to respect user themes, default foreground/background, XDG config, and NO_COLOR/similar conventions.
  • Strong push to avoid illegible color combinations, relying on color alone, or gratuitous emoji/Unicode, especially for copy/paste and screen readers.
  • Disagreement on “don’t use more than 16 colors”: some argue for truecolor when terminals support it; others prioritize predictability and user palettes.

Paths, Tilde Expansion, and Globbing

  • Tilde expansion (~, ~user) is clarified as strictly a shell feature, not a POSIX path feature.
  • Some argue REPLs/TUIs should implement tilde expansion; others warn this adds complexity and edge cases.
  • Differences noted: globbing is shell-side on Unix but often program-side on Windows.

Broader CLI Design Practices

  • Multiple references to CLI guidelines and Unix texts as de facto standards.
  • Recommendations: handle non‑TTY (pipelines) cleanly, don’t assume a terminal type, offer man pages plus --help, support response files (@file), and reload config on SIGHUP for long‑running daemons.
  • Some see many “rules” as outdated or ergonomically poor, arguing for breaking conventions when they clash with better UX.