CLI Style — An elegant interface for a more automated age.

Speak in sentences.

Subject, object, verb, target, modifier. app noun verb target --modifier. A command line is a sentence in an imperative language; make it parse like one. What can be said aloud can be guessed, and what can be guessed can be composed by a script that never read your manual.

Use subcommands, not mode flags.

Hierarchy carries meaning that flags can't. If you're reaching for a mode flag, what you wanted was a subcommand. The tree is a map that can be explored a level at a time, and the path is the address: no hidden mode silently changes what the same words mean.

Make invalid combinations impossible.

A subtree owns its flags. If two options can't coexist, design the grammar so they cannot be combined in the first place: split conflicting actions into separate subcommands, and collapse mutually exclusive choices into a single valued flag. Where shorthand flags like --quiet and --verbose must coexist on the same command, define a clear precedence (for example, --verbose overrides --quiet, or last flag wins) rather than failing with a flag-conflict error.

Name the application for typing.

Short, lowercase, no punctuation, easy to say. The name will be typed thousands of times and spoken in hallways. Check that it isn't already taken by something on a normal system: shadowing an existing command is a bug you inflict on everyone.

Few verbs, many nouns.

Reuse the same verb across every noun. If list works on clusters, it works on users, keys, and regions too. Eight verbs applied to twenty nouns is a smaller thing to learn than forty bespoke commands, and it teaches itself: anyone who has mastered half your application has already mastered the rest.

The target is positional; everything else is a flag.

Pass the target of the command as a positional argument and every other option as a named flag. Never put an optional positional argument before a required one, and never change what a positional argument means based on the one before it. If a reader has to count positions to know what 3 or true means, it should have been a flag.

Honor --, the end of flags.

Everything after it is data, even if it starts with a dash. Filenames, search patterns, and arguments forwarded to a wrapped program all depend on it. Free to support, expensive to omit.

Convention over configuration.

The common path takes no flags. Every flag a user must pass is a decision you declined to make for them. Make the default right and the first attempt is usually the correct one.

One flag, one meaning, everywhere.

Consistent inside your application, and consistent with everyone else's. A novel spelling of a common idea is a tax you charge every person who types it and every agent that tries to guess it.

Long flags are for scripts; short flags are for hands.

Long flags are what get written into scripts, documentation, and issue comments, because they explain themselves. Short flags are a convenience for the handful of options typed daily, and a permanent allocation from a very small namespace. Spend them carefully.

Precedence is a contract.

Published, stable, inspectable. Anyone can ask the application where a value came from and get a straight answer: the layer that won, named, instead of bisecting their dotfiles.

Match configuration to lifespan.

How long a value should live tells you where it belongs. That's the whole decision, and it's almost always obvious once asked.

Put configuration where the platform says.

Use the operating system's standard directories on Linux, macOS, and Windows, and honor XDG_CONFIG_HOME, XDG_CACHE_HOME, and XDG_STATE_HOME when set. Don't scatter dotfiles across the home directory, don't invent a new location, and keep cache separate from configuration so clearing one never destroys the other.

Run with no configuration at all.

A fresh install on an empty machine must do something useful. Configuration files are an optimization for repeat users, never a prerequisite. An application that can't start without a config file can't be tried, by anyone or by anything.

Read stdin, write stdout; compose.

Read stdin when no input file is given. Write to stdout rather than to a file chosen on the user's behalf. An application that composes is worth several that don't; composition is how your readers build things you never anticipated.

Name the outcome, not the mechanism.

--preview beats --dry-run. --force describes your internals; --overwrite describes what happens to someone's files. Name the flag after the thing the user cares about, which is never your implementation. When the name states the effect, reading it is knowing it: no translation step, for any reader.

Use one word whenever possible.

--preview is easier to type and clearer than --dry-run; --fresh beats --no-cache-write. Single-word commands and flags force you to find the real word for the concept, and they eliminate separator and casing ambiguity — nobody has to guess whether you spelled it --no-cache, --nocache, or --NoCache.

Show the change, not the summary.

Show the delta you would produce; don't narrate the steps you might take. "Would create 3 resources" is a log line. The resources themselves are an answer: a person can review it like a patch, a pipeline can evaluate it, before anything is applied.

Be idempotent, or refuse.

Re-running a command either reaches the same state safely or fails cleanly and changes nothing. Half-applied is the one unacceptable outcome. Retries are how everything recovers: a dropped connection, a Ctrl-C, a flaky agent. Making them safe makes the whole failure model simple.

Match confirmation to consequences.

Scale friction to the cost of recovery, not the size of the command. Undoable changes should run immediately with zero prompts. Recoverable changes (restarting a service, rotating a key) proceed by default and support --preview. Unrecoverable deletions confirm once (y/N at a terminal, --yes in automation). Catastrophic actions—or bulk operations with destructive blast radius if mis-scoped—print what will be destroyed and require naming the target itself (interactively or via --confirm <target>), never a blanket --yes.

Do only what the name promises.

A command called status does not refresh a cache, rotate a token, or send telemetry. Hidden side effects are how an application loses the trust it needs to be given credentials and let loose, by a person or by a program with far more authority than attention.

Recognition over recall.

Nobody should have to remember what you named things. Complete subcommands, flags, and live resource names at the prompt, and list valid choices whenever an option takes a fixed set. What can be discovered can be used; what must be recalled from memory will be mistyped or hallucinated.

Make the application self-documenting.

Generate help text, completions, man pages, and machine schema from one source — the command tree itself — so they cannot drift. Documentation that ships inside the binary can't go stale relative to the binary, and what's installed is always what's described.

Put real examples in every command's help.

A flag table explains what is legal; examples show what is idiomatic. Include three concrete invocations someone can copy and run—the common path, a preview or modifier path, and a piped or scripted path. For both people and agents, three working commands teach the grammar faster than fifty lines of flag descriptions.

Help everywhere.

Running the bare application prints help rather than an error. Support app help as a subcommand alongside -h (terse, fits on a screen) and --help (complete) at every level. Help that was asked for is a success and exits zero; help printed because someone got the command wrong is a failure and exits two.

Version and capability are queryable.

The version subcommand prints what a bug report needs: version, commit, and platform. Pair app version --json with app help --json so a script or agent that has never seen your application before can inspect its build and full command tree in one call.

End help with where to go next.

One line: the documentation URL and how to report a bug. It costs a line and saves a search.

Streams are typed.

stdout is data. stderr is everything else: logs, progress, warnings, prompts. No exceptions, no "just this one status line." Typed streams are what let a person pipe the output somewhere and still watch what the application is doing, and let a parser read stdout without stripping the chatter out first. Telemetry never corrupts the payload.

Print less than you think you should.

Terse by default, --verbose to expand. Verbosity is a request, never a default. Every line printed is spent from someone's finite budget — attention on a screen, context in a window — and a wall of successful output is exactly what hides the one line that mattered.

Machine output is a mode, not a fallback.

--json on every command that returns data, including errors. Generate it from the same values as the human rendering rather than assembling it separately: two code paths become two behaviors, and the machine path is the one nobody notices breaking.

Say little on success.

Print what was produced, or print nothing. "Successfully completed operation" tells no one anything the exit code didn't. Silence is a valid and often correct response to a job well done.

Anything conveyed by color must also be carried by a word or a symbol. Color is a courtesy one reader can accept, and gibberish to everything else.

So decorate, never encode. Turn it off when stdout isn't a terminal, when NO_COLOR is set, and when --no-color is passed.

Spinners and bars are for a human watching. Without a TTY, print nothing, or one line per meaningful milestone.

Communicate responsively.

Silence on a slow operation looks identical to a hung process or a blocked stdin read. Never leave the caller guessing whether the application is working or wedged: when an operation waits on the network, a lock, or a remote state transition, emit what you are doing on stderr and update it as phases change. Pair status updates with --timeout so automated callers can bound the wait.

Design the empty result.

Zero results is a legitimate answer, not an error, and exits zero. On a terminal, say what was searched and suggest the next move. Under --json, return []; when piped as plain text, emit zero lines so wc -l counts zero rather than one.

Keep plain output line-oriented.

One record per line, stable field order, no decorative box drawing in the default view. Tables are for terminals; lines are for pipelines. If your pretty format can't be cut, sorted, and grepped, provide one that can.

Stream results as you get them.

Don't collect everything in memory to print it perfectly aligned at the end. Output that appears incrementally can be watched, piped into a running pipeline, and interrupted usefully.

Every prompt has a flag equivalent.

Every prompt, confirmation, and editor input needs a flag equivalent, and every confirmation needs --yes. Never open an editor or a pager unasked without a flag to supply the content directly. Any workflow that can be completed interactively must also work in a single non-interactive command line — in CI, in a script, and in an agent.

Check each stream independently. stdout redirected to a file while stderr is still a terminal is the normal case, not the exotic one, and it should produce clean data in the file and a live display on screen. The right behavior for every stream depends on what is actually attached, so look before you draw.

If required parameters are missing and a person is at a terminal, ask for them instead of exiting with an error. Prompt only for what was left out — never re-ask what was already supplied by flag or configuration.

Print the equivalent non-interactive command afterward, so the person who answered three prompts today can script it tomorrow, and an agent reading shell history learns the flag form.

Exit promptly when interrupted.

Ctrl-C means now. Clean up what must be cleaned up — temporary files, a partial write, a terminal left in raw mode — and get out. An application that ignores the first interrupt teaches everyone to reach for a harder signal that skips cleanup entirely.

Fail forgivingly.

Accept near-misses: edit distance on subcommands and flags, aliases for everything you ever renamed. Being strict about spelling has never once prevented a bug. "Did you mean restart?" saves a person a trip to --help and gives an agent the exact token to retry.

Errors say what to do next.

What failed, why, and the command that would fix it. An error that only reports state is half an error.

Exit codes are part of your API.

Zero means it worked. Two means the command line was wrong. Beyond that, define your codes, document them, never renumber. Distinguishing "the thing doesn't exist" from "the network failed" turns a retry loop from a guess into a decision.

One sentence first, detail underneath.

The first line names what failed, in the user's terms. Stack traces, request IDs, and internal context go below, or behind --verbose. Nobody reads down; everybody reads the first line.

Errors have a machine form too.

Under --json, a failure is structured output on stderr: a stable code, a message, and a remediation field, not a paragraph of English where a parser expected an object. Recovery should be a step to take, not a string to guess at.

An unexpected crash asks to be reported.

If the failure is your bug and not the user's mistake, say so plainly and give the URL, the version, and the command that triggered it. Distinguish clearly between "you did something wrong" and "we did something wrong." Confusing the two makes people stop reporting anything.

Make state changes atomic.

Write files to a temporary path and rename into place; apply configuration and state updates completely or not at all. A process can be killed at any instant, and an interrupted operation that corrupts the state it was updating is the failure people remember for years.

Add, don't subtract.

Aliases outlive renames; old flags keep working. Your users' scripts are your real API. Now so are their agents' learned habits and training weights, which no migration notice can reach in and update.

Deprecate with a date and a migration plan.

State what's going away, when it will be removed, and the exact replacement to use instead. Warn on stderr so the notice never corrupts stdout, and keep the old name working for the entire announced window. A deprecation without a date is a threat; one without a migration plan is an abandonment.

The machine format is the strictest promise you make.

Human output can be redesigned; people adapt. Structured output cannot. Adding a field is safe. Everything else — removing, renaming, retyping, reordering an array that carries meaning — breaks something silently and at a distance. Version the format if you must change it, and serve both.

Ship one file that runs anywhere.

A single self-contained binary, no runtime to install first. Every dependency standing between someone and their first successful command is a place they give up, and a CI container or agent provisioning its workspace has even less patience for a five-step setup than a person does.

As easy to remove as to install.

Document what you wrote and where. Better: put everything in two predictable places, so deleting the binary and one directory removes the application completely. Nobody trusts software that won't leave.

Secrets never come from arguments.

Arguments are visible in the process list, shell history, CI logs, and agent transcripts. Accept credentials from stdin, a file path, an environment variable, or the system keychain. If you offer a flag, have it take a path or a reference, never the secret itself.

Be honest about what leaves the machine.

Say what you send and to where, and let it be turned off with both a flag and an environment variable. An application that's quiet about its network activity will eventually be found out, and the trust doesn't come back.

Write only where you were asked to write.

Don't drop credentials, caches, or state into the working directory, and don't edit a file the user didn't name, especially not their shell profile. If installing completions means modifying a dotfile, print the line and let them add it.