Plan — Announcing cli.style (working title)

Slug: announcing-cli-style · Target: ~600 words · Tone: announcing, personal (I built this) Audience: developers and agent builders · Sole media: cli.style homepage screenshot

Thesis

cli.style is the Human Interface Guidelines for the command line: a numbered, citable style guide (10 parts, 56 principles) for designing CLIs for their two readers — the person who types a command and the program (agent/CI/script) that runs one. The same qualities that make a CLI good for people make it reliable for agents; agents just raise the cost of ambiguity.

Counter-position

Against the idea that the GUI desktop, the web, or AI would replace the terminal: it kept growing alongside each of them. Also against “craft by oral tradition”: until now the terminal had no equivalent of platform HIGs, just scattered man pages and tribal knowledge.

Sections (claim-shaped heading + concrete anchor + budget)

An agent stuck on a prompt is a design bug (140 w) — concrete anchor: the opener is a deliberately flagged, one-sentence illustrative scenario (a non-interactive caller — script or agent — hangs on an interactive prompt or misreads a spinner rendered into stdout). Keep it to one sentence, then argue. The command line grew alongside the GUI, the web, and cloud dashboards because plain text is the interface that composes most naturally. With agents, plain text is increasingly the interface automation actually uses.
The terminal finally gets its own design guidelines (130 w) — 56 principles, 10 parts, permanent anchors for citing in reviews and PRs (e.g. #preview-is-a-diff); covers grammar (subcommands not mode flags), flags, typed streams, exit codes; framework-agnostic — Cobra/Viper/pflag embody it (github.com/spf13/cobra, viper, pflag linked), but nothing is Go-specific.
Only four principles differ for agents (120 w) — you don’t need two interfaces; just four (color, progress, terminal detection, prompts) read differently per reader and are marked with a divergent aside — and they are where most of the breakage I see lives (my observation from designing and writing CLI tools, incl. Cobra/Viper/pflag/Hugo).
Coding agents can now audit your CLI against the guide (110 w) — the guide ships as a SKILL.md at github.com/spf13/cli-style, so coding agents build and audit CLIs against it automatically; link to install.
Anchored principles make design reviews citable (100 w) — close: read it, cite principles by anchor in design reviews and PRs, install the skill.

Media

Single screenshot of https://cli.style homepage (hero + grammar diagram) — page bundle cli-style-home.png, used as relImage hero with image_fit = "contain" (wide desktop shot; square crop would butcher it). Alt text: “cli.style homepage: 56 numbered principles across 10 parts, with a diagram showing a command line parsed as a sentence.”

External claims / evidence

56 principles, 10 parts, permanent anchors, fictional app examples — cli.style homepage.
4 divergent principles (color, progress, terminal detection, prompts) — cli.style homepage.
SKILL.md published at github.com/spf13/cli-style — cli.style homepage header/footer + repo.
Cobra/Viper/pflag built with these principles — cli.style homepage; repos linked as evidence (github.com/spf13/cobra, viper, pflag; gohugo.io for Hugo).
“The command line grew alongside each wave” / “increasingly the interface automation actually uses” / “most breakage lives in the four divergent principles” — author’s opinion/observation from designing/writing Cobra, Viper, pflag, and Hugo, stated as such in the post.
The opening failure-mode anecdote is hypothetical/composite (a generic script or agent hanging on a prompt), presented as illustration, not a named incident.

Steve checkpoint

Structure approval — approve this outline before drafting begins.