CLI design standards for commands, flags, args, exit codes, I/O, config, help text, errors, progress, interactivity, color, typography, components, and documentation. Use when designing new CLIs, implementing commands, writing help text, formatting terminal output, choosing flags, documenting a CLI, reviewing CLI standards, unifying output patterns, writing error messages, defining color systems, or choosing exit codes. Use as reference when planning CLI improvements, reviewing copy and tone, or redesigning command output layout.
Pure design knowledge for command-line interfaces, organized into four layers.
The Four-Layer Model
Every CLI decision falls into one of four layers, ordered by risk of change (highest first):
Contract > UX > UI > Docs in terms of breaking-change severity.
</description> <principles>Eight universal principles apply across all layers (full definitions in references/principles.md):
<standards_hierarchy>
When conventions conflict, follow this precedence:
</standards_hierarchy>
<reference_index>
Foundations
references/principles.md — Eight universal design principles with application guidance and precedence rulesContract Layer
references/contract/command-structure.md — Command naming, subcommand hierarchies, grammar patterns, standard verbsreferences/contract/flags.md — Short/long flags, boolean/value/repeatable types, standard names, deprecationreferences/contract/arguments.md — Positional args, ordering, stdin handling, -- delimiterreferences/contract/exit-codes-and-signals.md — Exit codes, signal handling, cleanup patternsreferences/contract/io-streams.md — stdout/stderr separation, output formats, piping, TTY detectionreferences/contract/configuration-hierarchy.md — Config files, env vars, XDG paths, precedence orderUX Layer
references/ux/help-system.md — Help text structure, usage strings, examples, flag descriptions, reference outputreferences/ux/error-messages.md — Error structure, actionability, did-you-mean, common error templates, JSON errorsreferences/ux/copy-style.md — Voice, tone, wording, vocabulary, tense, punctuation, copy patternsreferences/ux/progress-and-feedback.md — Spinners, progress bars, verbosity levels, non-TTY behaviorreferences/ux/interactivity.md — TTY detection, prompts, confirmations, dry-run interaction, non-interactive modereferences/ux/discoverability.md — Shell completions, contextual suggestions, onboarding, command discoveryUI Layer
references/ui/color-system.md — Semantic palette, NO_COLOR/FORCE_COLOR, accessibility, auditing color usagereferences/ui/typography-and-spacing.md — Output anatomy, text hierarchy, alignment, width, cross-command consistencyreferences/ui/terminal-components.md — Glyphs, tables, trees, diffs, file lists, search results, JSON modeDocs Layer
references/docs/cli-documentation.md — README structure, command docs, flag docs, exit codes, changelogs, accuracy</reference_index>