Command line interface guidelines (2021)

CLI vs TUI vs GUI

• Some argue TUIs are ideal for “general audience”: consistent font size, dense but structured layouts, keyboard efficiency, and SSH-friendliness.
• Others counter that TUIs share many GUI drawbacks, are no more discoverable, and that well-designed GUIs can mimic TUI structure without terminal constraints.
• Several note CLIs are in a “golden age” in absolute user numbers, but debate whether they’re more important relative to all computer users.

Shells, composition, and POSIX tools

• Debate over whether Unix commands were primarily for programmatic use vs interactive shell use; agreement that shells are programming languages but not ideal for large programs.
• Strong support for “shell as glue”: tiny shell scripts that orchestrate C or other binaries can replace much larger programs.
• POSIX getopt is widely referenced but clarified as a POSIX, not language, feature.

Command-line design conventions & pain points

• Mixed views on nested subcommand hierarchies: they can reduce local complexity but make discovery harder vs one big help page.
• Complaints about flag capitalization inconsistency and combined short flags; some wish new tools favored long, explicit flags and avoided tricky short-option semantics.
• Calls to avoid arbitrary subcommand abbreviations, especially in scripts, to preserve future extensibility.
• Some feel the guidelines document is long, others see it as concise relative to typical UI guides.

Machine-readable output and formats

• Tension between human- and machine-readable CLIs is called “broken by design”; suggestions include --json modes and/or IO-format environment variables.
• Concerns that environment variables can both simplify global control and introduce subtle bugs or bloat.
• PowerShell is raised as a partial solution with structured output, but also criticized as verbose and sometimes hard to use.

Safety, dry run, and destructive commands

• Strong support for --dry-run / “what-if” behavior, sometimes even as the default requiring an explicit --execute/--commit.
• Suggested patterns:
  • Tools that only emit shell commands, letting users inspect/edit and then pipe to sh.
  • try-style sandboxing via overlay filesystems.
• Some reimplement core utilities to add safety prompts; others prefer shell aliases with -i.

Secrets handling

• Guideline against secrets in environment variables is debated.
• Alternatives discussed: credential files with strict permissions, systemd credentials, and “run this command to fetch secret” hooks that can delegate to password managers or services.
• Secrets managers are seen as convenient in managed environments; less clear for personal projects.

Help, documentation, and discoverability

• Frustration with tools that reject -? or similar as help instead of just printing usage.
• Some disappointment that the guidelines only say “consider” man pages; others note man pages and rich --help remain crucial for large CLIs.

Stdout/stderr and output UX

• Strong argument that all logging, progress, animations, and status messages belong on stderr; stdout should be reserved for the “primary result” to keep pipelines reliable.
• Animations on non-TTY stdout in particular are criticized as breaking logs; some say animations should never be on stdout at all.
• Emojis and decorative symbols are divisive: some find them helpful and visually scannable; others dislike inconsistency, terminal rendering issues, and perceived frivolity, suggesting they be optional and redundant with text.

Versioning, deprecation, and CLI complexity

• CLI deprecation is seen as uniquely hard because commands get scripted immediately and lack version pinning semantics common to libraries.
• Workarounds like copying binaries to private paths are discussed but criticized as fragile due to dependencies.
• Growth of “mega-CLIs” (e.g., multi-subcommand tools) is lamented as a departure from the classic “do one thing well” Unix ethos, but also acknowledged as a practical response to modern complexity.