Disclose a CLI's surface progressively
State: open/draft
Summary
Section titled “Summary”- A command-line tool reveals itself in tiers: the first screen is the smallest set that gets someone working, and everything else is one explicit question away.
- Each tier names the next, so nothing is hidden; a reader never has to guess that a deeper tier exists.
- Exactly one tier is complete, and a mechanical check proves it stayed complete.
Statement
Section titled “Statement”A command-line tool’s surface is revealed in tiers rather than all at once. The first thing a reader sees is the smallest set that gets them working; the full flag list, the per-subcommand detail, and the model behind the tool are each one explicit question further in. Progressive disclosure is not omission. Every tier names the tier below it, so the deeper surface is discoverable by reading rather than by guessing, and at least one tier is complete.
A help text that prints everything prints nothing
Section titled “A help text that prints everything prints nothing”The reader scans fifty lines to find the three they needed, and the flag that answers their question looks the same as the flag nobody has ever passed. Every reader pays that cost on every invocation, and it grows with every flag added.
Exhaustiveness is not discoverability
Section titled “Exhaustiveness is not discoverability”A short first tier that names guide, <subcommand> --help, and --help --all is more
discoverable than a long one that names nothing: it tells the reader where to look next. An
exhaustive dump only answers the questions the reader already knew to ask.
Tiers are how a tool stays learnable while it grows
Section titled “Tiers are how a tool stays learnable while it grows”Without them, every capability added makes the first screen worse for everyone who does not use it. That pressure makes maintainers stop adding useful flags, or add them undocumented. With tiers, the first screen is stable and growth lands where it belongs.
How it applies
Section titled “How it applies”- Tier 1,
--helpand the no-argument invocation: what the tool is, the two or three ways in, the flags most invocations use, and the names of the deeper tiers. It fits a terminal without scrolling. - Tier 2,
<subcommand> --help, or a--help --allthat prints the whole flag list. Complete for the surface it covers. - Tier 3, a
guide-style command and the written docs: the model, the security posture, the extension contract. Addressable by topic, so a reader or an agent can ask for one section rather than the document. - Every tier names the next. A first screen that ends without pointing anywhere has failed the principle even if it is short.
- One tier is complete, and a test says so. For every flag the parser accepts there is a tier that documents it, asserted mechanically rather than by review.
- Defaults are stated where they bite, not collected in an appendix a reader reaches only after the surprise.
- Tiers are earned by surface area. A tool with one job and three flags has one tier; adding ceremony to a small tool is the same mistake in the other direction.
Examples
Section titled “Examples”waypost guide/guide <topic>/guide topics: the third tier, addressable by section, and written for “a person, or a model, who has the binary and not the README”.waypost config --help,trust --help,clean --help: each subcommand answers for itself rather than swelling the top-level text.sdlc --advanced: a disclosure tier in a single flag; the common nouns first, the whole registry on request.- The counter-example this principle was written against:
waypost --helpprinted every flag, every subcommand, the trust posture, and the terminal key line in one block of about 45 lines, with no shorter tier and nothing namingguide.
Implications
Section titled “Implications”- Downstream of P-0009-surface-system-shape. Surfacing shape and drowning the reader are different things; tiers are how a tool does the first without the second.
- Paired with P-0015-cli-serves-three-readers. An agent asks for the deep tier directly and does not need it on screen by default, which is what makes a short first tier affordable.
- A completeness check becomes a required test, not a review habit. The cost of tiering is that a flag can now go undocumented in every tier, and only automation catches that.
- It does not say split the documentation until no complete reference exists. Fragmentation with no complete tier is the failure this principle is most likely to be misread into.
- The working test for tier 1: would a reader who has never run this tool get something useful done from this screen alone, and know where to look for what it did not say? If either half fails, the tier is wrong.
- Tier 1 shrinking when a capability is added is normal, not a regression. What must never shrink is the complete tier.