CLI Guidelines – A guide to help you write better command-line programs

Hello HN!<p>We’re Ben, Aanand, Carl, Eva, and Mark, and we made the Command Line Interface Guidelines.<p>Earlier this year, I was working on the Replicate CLI [0]. I had previously worked on Docker so I had a bunch of accumulated knowledge about what makes a good CLI, but I wanted to make Replicate <i>really</i> good, so I looked for some design guides or best practices. Turns out, nothing substantial had been published since the 1980s.<p>On this search I found a superb blog post by Carl about CLI naming [1]. He must be the only person in the world who cares about CLI design and is actually a good writer, so we teamed up. We also were joined by Aanand, who did loads of work on the Docker CLIs; Eva, who is a technical writer, to turn our scrappy ideas into a real piece of writing; and Mark, who typeset it and made a super design.<p>We love the CLI, but so much of it is a mess and hard to use. This is our attempt to make the CLI a better place. If you’re making a tool, we hope this is useful for you, and would love to hear your feedback.<p>Some of it is a bit opinionated, so feel free to challenge our ideas here or on GitHub! [2] We’ve also got a Discord server if you want to talk CLI design. [3]<p>[0] <a href="https:&#x2F;&#x2F;replicate.ai&#x2F;" rel="nofollow">https:&#x2F;&#x2F;replicate.ai&#x2F;</a><p>[1] <a href="https:&#x2F;&#x2F;smallstep.com&#x2F;blog&#x2F;the-poetics-of-cli-command-names&#x2F;" rel="nofollow">https:&#x2F;&#x2F;smallstep.com&#x2F;blog&#x2F;the-poetics-of-cli-command-names&#x2F;</a><p>[2] <a href="https:&#x2F;&#x2F;github.com&#x2F;cli-guidelines&#x2F;cli-guidelines" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;cli-guidelines&#x2F;cli-guidelines</a><p>[3] <a href="https:&#x2F;&#x2F;discord.gg&#x2F;EbAW5rUCkE" rel="nofollow">https:&#x2F;&#x2F;discord.gg&#x2F;EbAW5rUCkE</a>

This is a great resource, thanks for the effort.<p>I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying.<p>There are tools such as pandoc that make generating manpages from various source formats very easy.<p>Perhaps it is just my grouchy old man syndrome…

These are some pretty good guidelines! Many thanks to the authors for writing them up.<p>Some nitpicks (what would HN be without nitpicks?):<p>&gt; If your command is expecting to have something piped to it and stdin is an interactive terminal, display help immediately and quit.<p>I disagree with this advice: being able to spoon-feed input into a program is <i>extremely</i> useful, and is part of the &quot;conversational&quot; CLI paradigm that the authors mention above. Commands that silently block on `stdin` <i>are</i> frustrating, but the right solution is to check `isatty(3)` and print an <i>informational</i> message rather than killing the program entirely.<p>&gt; Check general-purpose environment variables for configuration values when possible<p>Consider adding `$IFS` to this! Commands that support different output models based on `isatty(3)` often neglect to support `$IFS`, making them more difficult to use in pipelines. This is especially handy in pipelines that need to deal with messy or untrusted inputs; I regularly use `IFS` with the ASCII field escape bytes.<p>&gt; Don’t bother with man pages.<p>Please <i>do</i> bother with them! Nobody needs to write raw roff or troff in 2020; there are plenty of high quality manpage generators[1][2][3] that will turn your Markdown&#x2F;ReST&#x2F;whatever documentation into sensibly formatted manpages. manpages are much easier to search than the medley of pseudo-formats that CLI tools choose to render their `--help` outputs with.<p>[1]: <a href="https:&#x2F;&#x2F;github.com&#x2F;rtomayko&#x2F;ronn" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;rtomayko&#x2F;ronn</a><p>[2]: <a href="https:&#x2F;&#x2F;pandoc.org&#x2F;" rel="nofollow">https:&#x2F;&#x2F;pandoc.org&#x2F;</a><p>[3]: <a href="https:&#x2F;&#x2F;www.sphinx-doc.org&#x2F;en&#x2F;1.4&#x2F;man&#x2F;sphinx-build.html" rel="nofollow">https:&#x2F;&#x2F;www.sphinx-doc.org&#x2F;en&#x2F;1.4&#x2F;man&#x2F;sphinx-build.html</a>

My advice as a user of CLI:<p>- no emojis please, ever<p>- if you want to make it look nice, use ANSI escape codes for color rather than emojis. even then, don&#x27;t use color alone to convey meaning because it will most likely get destroyed by whatever you&#x27;re piping it to.<p>- please take the time to write detailed man pages, not just a &quot;--help&quot; screen<p>- implement &quot;did you mean?&quot; for typos (git style) and potentially dangerous commands<p>- separate the interface into a tree of subcommands (Go&#x2F;Docker&#x2F;AWS style) rather than a flat assortment of flags<p>- if you are displaying tabular data, present an ncurses interface<p>- (extremely important) shell completion for bash and zsh

Hah. This is a topic that&#x27;s dear to my heart and have blogged occasionally about it... but never in such a comprehensive form. Great job! Now... I gotta read through everything.<p>But... here is a series of blog posts in which I covered similar themes years ago: <a href="https:&#x2F;&#x2F;jmmv.dev&#x2F;series.html#CLI%20design" rel="nofollow">https:&#x2F;&#x2F;jmmv.dev&#x2F;series.html#CLI%20design</a><p>And here is another single post that touches upon a single guideline I came across while skimming through the text: <a href="https:&#x2F;&#x2F;jmmv.dev&#x2F;2020&#x2F;08&#x2F;config-files-vs-directories.html" rel="nofollow">https:&#x2F;&#x2F;jmmv.dev&#x2F;2020&#x2F;08&#x2F;config-files-vs-directories.html</a> . It might be helpful in providing more details about the _whys_ behind each guideline.<p>Lastly, I&#x27;ll also mention the &quot;Producing open source software&quot; book by Karl Fogel, which provides a lot of useful advice too, especially on how to ship the tools: <a href="https:&#x2F;&#x2F;producingoss.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;producingoss.com&#x2F;</a>

&gt; The command line of the past was machine-first<p>&gt; Traditionally, UNIX commands were written under the assumption they were going to be used primarily by other programs<p>Is there any real factual basis for these claims? I find them hard to believe, considering the origins of UNIX and the fact that shell was the primary (or even only) user interface for the system, and it was pretty much from day 1 designed as an interactive system (contrasted to the more batch&#x2F;system oriented mainframes of IBM etc)

This is a great resource. I will return to read it closely next time I am designing a CLI.<p>One thing that puzzled me: `git push` is given as an example of the principle &quot;If you change state, tell the user&quot;. Its output is:<p><pre><code> $ git push Enumerating objects: 18, done. Counting objects: 100% (18&#x2F;18), done. Delta compression using up to 8 threads Compressing objects: 100% (10&#x2F;10), done. Writing objects: 100% (10&#x2F;10), 2.09 KiB | 2.09 MiB&#x2F;s, done. Total 10 (delta 8), reused 0 (delta 0), pack-reused 0 remote: Resolving deltas: 100% (8&#x2F;8), completed with 8 local objects. To github.com:replicate&#x2F;replicate.git + 6c22c90...a2a5217 bfirsh&#x2F;fix-delete -&gt; bfirsh&#x2F;fix-delete </code></pre> The state change information only comes after many lines of (IMO) unnecessary detail about the inner workings of `git push`. I think this would be much better:<p><pre><code> $ git push Writing objects: 100% (10&#x2F;10), 2.09 KiB | 2.09 MiB&#x2F;s, done. Pushed 10 objects to github.com:replicate&#x2F;replicate.git + 6c22c90...a2a5217 bfirsh&#x2F;fix-delete -&gt; bfirsh&#x2F;fix-delete</code></pre>

A few additions to these recommendations:<p>&gt; Show full help when -h and --help is passed<p>It is also a good idea to support --version<p><pre><code> $ make --version GNU Make 4.1 Built for x86_64-pc-linux-gnu Copyright (C) 1988-2014 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later &lt;http:&#x2F;&#x2F;gnu.org&#x2F;licenses&#x2F;gpl.html&gt; This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. </code></pre> &gt; Use standard names for flags, if there is a standard.<p>In the interest of consistency across tools, I recommend consulting the Table of Long Options from the GNU Coding Standards.<p><a href="https:&#x2F;&#x2F;www.gnu.org&#x2F;prep&#x2F;standards&#x2F;html_node&#x2F;Option-Table.html" rel="nofollow">https:&#x2F;&#x2F;www.gnu.org&#x2F;prep&#x2F;standards&#x2F;html_node&#x2F;Option-Table.ht...</a><p>Some long options that are particularly helpful, when appropriate:<p><pre><code> ‘dry-run’ ‘-n’ in make. ‘null’ ‘-0’ in xargs. </code></pre> Also, options that increase safety:<p><pre><code> &#x27;no-clobber&#x27; ‘-n’ in mv # do not overwrite an existing file &#x27;overwrite&#x27; ‘-c’ in unshar # even better than --no-clobber, require explicit # permission before overwriting existing files </code></pre> edit:<p><i>Never</i> try to be &quot;smart&quot; or &quot;magic&quot; and <i>guess</i> what the user intended! DWIM can appear useful at first, but we&#x27;ve known for a <i>long</i> time that DWIM behavior is <i>dangerous</i>[1].<p>[1] <a href="https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=15628014" rel="nofollow">https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=15628014</a>

Great doc!<p>I disagree about abandoning manual pages. I always reach for `man foo` even before `foo --help`.<p>Missing detail: Exit codes should be restricted to a range of 0..255 inclusive. Many POSIX system calls only forward the low-order 8 bits of the exit code to a parent process.

Loving this!<p>As a nit:<p>&gt; Let the user escape. Make it clear how to get out. (Don’t do what vim does.) If your program hangs on network I&#x2F;O etc, always make Ctrl-C still work. If it’s a wrapper around program execution where Ctrl-C can’t quit (SSH, tmux, telnet, etc), make it clear how to do that. For example, SSH allows escape sequences with the ~ escape character.<p>I find it confusing that vim is considered less discoverable here than SSH. In either case, you can find the information in the manual (not ideal, but a baseline). In the case of vim, when you hit ctrl-c it tells you how to leave for real. So far as I&#x27;m aware, there&#x27;s no real way to discover the magic ~ invocations in SSH except resorting to the manual or exhaustively trying every key combo with no evidence that you&#x27;re on the right track or that there&#x27;s even a track to be on.<p>Also, vim <i>is</i> (in part) a wrapper around program execution.

<p><pre><code> &gt; Use a command-line argument parsing library where you can. &gt; ... &gt; Python: Click, Typer </code></pre> What&#x27;s the problem with using the python standard library argparse?<p>I would frown upon adding a dependency for such a core feature as argument parsing, unless it brings strong benefits. And even then, I&#x27;d recommend to use the standard lib and to switch to the other libs only when necessary.

&gt; &quot;Don’t bother with man pages. [...] Not enough people use man pages [...] your time is best spent improving web docs and built-in help text.&quot;<p>I couldn&#x27;t disagree more.

The software I will use to invoke your command immediately send EOF to your process&#x27;s stdin. Almost all traditional Unix command do something sensible in response. &quot;mv -i&quot; for example, refrains from moving anything. The software I prefer to use to run your command has no provision for your command&#x27;s trying to engage me in a conversation.<p>If I am sufficiently motivated to run your command, I might choose to re-run your command in Terminal.app. For example, I ran whatever command needed to install Command Line Tools in Terminal.app so that I could indicate my agreement to its terms and conditions by my typing &quot;y&quot;. But your command is probably not important enough for me to bother running it in Terminal.app.<p>If I use your command incorrectly (e.g., if I misspell a flag), and your command tells me so, then I am willing to issue a new, corrected command line, and in fact I have the patience to try a command over and over, varying the command&#x27;s arguments and the command&#x27;s environment variables till I get it right.<p>But I no longer have the patience for things like vim or mutt or lynx -- i.e., programs that have what one might call a terminal user interface. (What about pagers? Well, I set the environment variable PAGER to cat. Similar to how Plan 9&#x27;s terminal works, the software I will use to invoke your command does not automatically scroll to the bottom of the process&#x27;s output: the window does not scroll unless I tell it to scroll, e.g., by hitting the page-down key.)<p>lynx was my primary browser for about 10 years, so it is not like I am ignorant of &quot;full screen&quot; terminal interfaces; I am just weary of them.

It&#x27;s kind of crazy that we still don&#x27;t have a standard computer readable way for a program to describe it&#x27;s argument structure in a computer readable way that could be used for command line autocomplete. E.g. something like an extra section in the binary that describes how arguments are processed.

&gt; Don’t bother with man pages.<p>&gt; If your help text is long, pipe it through a pager.<p>&gt; Use formatting in your help text.<p>So reimplement man in a non-standard way? No thanks. Keep --help short and concise and then have a separate man page with all the details. Don&#x27;t just ignore standards and conventions because not all operating system agree on them.<p>The languages of the the argument parsing libraries listed (Go, Node, Python, Ruby) is also kinda suspect when many such tools are written in C.<p>&gt; Use symbols and emoji where it makes things clearer.<p>Eww. And the example is pretty bad too with a number of meaningless icons.<p>&gt; By default, don’t output information that’s only understandable by the creators of the software.<p>Except people with post the default output if they are having problems and having all useful information here saves having to ask for it. Also, don&#x27;t underestimate your user&#x27;s abitlity to understand stuff.<p>&gt; Use a pager (e.g. less) if you are outputting a lot of text.<p>&gt; A good sensible set of options to use for less<p>Stop right there. If you going to automatically use a pager, at least use the preferred one the user has specified in their environment. $PAGER is even mentioned later in the environment variable section.

WRT man pages:<p><i>&gt; and they don’t work on Windows</i><p>My cygwin install says otherwise.<p>And even if that were not the case I wouldn&#x27;t not do something useful because of a deficiency in a particular platform. We have enough issues with that via needing to support IE11 still in the day job! Include the man page on the other documentation. You probably already have it written and can convert it from other docs so it might be very little work.

Nice initiative!<p>A few remarks :<p>- the intro text is way too long<p>- you contradict yourselves about stdout :<p><pre><code> `Log messages, errors, and so on should all be sent to stderr.` `Don’t treat stderr like a log file, at least not by default.`</code></pre>

The command line, in terms of the terminal emulator, really needs to evolve to more of a Meta-X mini-buffer pattern.<p>People keep circling around the sweet spot which is a fixed location command input area that outputs, in addition to text streams, any variety of multi-media.<p>On one end you&#x27;ve got a set of people doing heroic designs in the terminal with all variety of UTF-8 characters. On the other end you&#x27;ve got things like Jupiter Notebook.<p>What I&#x27;m looking for is something like the Mattermost UI without the chat aspect being front and center. Or Emacs, but with the ability to embed Youtube videos in a buffer.

Yes. Please ditch the man pages and instead get out of the terminal and get tracked in the browser. Like this website which needs Google ad tracking.

&gt; If your help text is long, pipe it through a pager.<p>I disagree that this is a good practice. This prevents me from using my terminal&#x27;s scrollback to read and&#x2F;or copy the text. If it comes up in a pager, I either have to re-run the help command every time I want to read it (super annoying when I&#x27;m trying to build a command line!) or open yet another window on my screen. And depending on the terminal, this might overwrite a part of the scrollback buffer I had important context in.<p>If I want to page the help output, I will pipe it to a pager myself.<p>If the help text is really so unreasonably long that it&#x27;s unsuitable for --help, hide it behind some other option that --help points me to.<p>Git does this (effectively treating &quot;-h&quot; the way every other CLI treats &quot;--help&quot;, and &quot;--help&quot; as a request to open a man page), and it&#x27;s incredibly annoying, because <i>no other CLI I use works this way</i>, so it screws up my muscle memory in a way that impacts both my usage of Git <i>and</i> of everything else.

Why are the font sizes so huge? The computed font size is 30px, compared to 12px for hn.

I think one emoji is one emoji too many. Many terminals do not support them. This also addresses the point of terminal independence you brought up elsewhere. The yubi key example looked like using emojis for the sake of using emojis. Several of them were redundant or only slightly relevant (test tube, hand, key).<p>In all honesty, I just really dislike emojis<p>The guidelines were all helpful otherwise. It shows that I could only find one nitpick.

&gt; Which means O_O and OwO are the only emoticons that are also valid environment variable names.<p>O_o

Could you make the site usable without javascript? Right now there&#x27;s a sidebar with a transparency that overlaps half of the paragraphs.

Nice read, makes me happy to see people invest in CLI.<p>&quot;Humans first&quot;... How about &quot;Humans with Tools first&quot; ? :)<p>I would say that ALL logging should go to stderr (level should be --configurable of course), so that when running a container for example I can capture all the logging easily on stderr. Also that [WARN], [ERROR], etc tags are quite nice to have in there when grep&#x27;ing over it.. Just saying :)<p>I would very much recommend The Art of UNIX programming, by Eric S. Raymond [0]<p>I used it extensively when developing Space.sh [1] (which was an insane shell script adventure purifying for the soul, but taxing on the brain).<p>Going full termie is the best choice I&#x27;ve made, thanks for a good read! \o<p>[0] <a href="http:&#x2F;&#x2F;www.catb.org&#x2F;esr&#x2F;writings&#x2F;taoup&#x2F;html&#x2F;" rel="nofollow">http:&#x2F;&#x2F;www.catb.org&#x2F;esr&#x2F;writings&#x2F;taoup&#x2F;html&#x2F;</a> (There is a PDF available somewhere too) [1] <a href="https:&#x2F;&#x2F;space.sh&#x2F;" rel="nofollow">https:&#x2F;&#x2F;space.sh&#x2F;</a>

I find it very interesting that the sources and &quot;further readings&quot; are more often than not SO or stack exchange links. It is just a recognition that the collective knowledge, as informal as it is on forums, is often used as reference material like one of those dusty algorithm textbooks or a software engineering design book.

I want both --help&#x2F;-h and man pages!

npm is terrible. Why? because the color and formatting outputs all kinds of escape characters. Guess what happens when Jenkins or other build systems try to render spinning ascii characters? What happens if color and spinning punctuation is allowed then developers who use configuration files for things like npm promote them to build with color escape character output enabled. It creates a mess of configuration files keeping separate build and development just for escape character configuration. My advice is no color and no escape characters if your CLI will ever be part of a build chain or is intended to output to logs. All it takes is for one usage to a log that doesn&#x27;t have &#x27;--no-color&#x27; and the binary characters will trip up diff and other tools that only work on text.

Thanks, this is sorely needed. Looking forward to taking time to dig more deeply into it.

Quit and help are the two most important and basic command that should have priority. The rest you can learn. These two is hard. Exit, quit, crt-d, crt-z... and help is even higher especially if you give an error response.

The most important part for me when creating a new CLI is the ability for the end user to debug the CLI themselves and step through it. This is much easier with e.g. Python, but fairly more complex with a binary built by Go

&gt;“Abandon a standard when it is demonstrably harmful to productivity or user satisfaction.” — Jef Raskin, The Humane Interface<p>Basically description of posix. Well, sure, it tries to solve an unsolvable problem, but still.

This is a good resource with a lot of good points. But,<p>&gt; Display output on success, but keep it brief.<p>Strong disagree. If everything went OK, or something is in progress, I don&#x27;t need to be notified; it&#x27;s distracting and makes me instinctively think something has gone wrong and needs my attention. <i>The Art of Unix Programming</i> got it right, &quot;Silence is golden.&quot;[1]<p>I&#x27;m disappointed that `git push` is their example of good CLI output, because I&#x27;ve truly hated git&#x27;s entire CLI design and philosophy for years. Git&#x27;s CLI is the opposite of what good CLI design should be in almost every way: a noisy, confusing, inconsistent, staggeringly complex misery. Do I really need to know that `git push` is enumerating obects? That it&#x27;s using delta compression using 8 threads? That it&#x27;s counting objects? That it&#x27;s compressing objects? That information is useless plumbing output that clutters and distracts for no purpose. Just do the work and keep quiet, with <i>at most</i> a progress bar for a long-running command--and even then it should be optional.<p>If people really want chatty output, include an optional --verbose flag, or even levels of verbosity with -v, -vv, -vvv, etc.<p>&gt; Use symbols and emoji where it makes things clearer.<p>Please, no. This is a fad right now and it&#x27;s also really distracting. Symbols and emoji don&#x27;t have common meanings and a symbol next to a header or plain text is not helpful, because the plain text already says what I need to know without the symbol. Does having an insect icon next to a header that says &quot;Error&quot; really improve clarity, or does a colorful icon in a sea of plain text needlessly distract? Should the icon have been an insect, or a stop sign? Or an exclamation mark in a circle? Or a traffic cone? Couldn&#x27;t all of those mean &quot;Error&quot;?<p>Their example of good emoji use includes a red X next to informational--not error--text (leading me to believe that an error occurred or something stopped unexpectedly) and some kind of duck-beak icon next to the text &quot;When the YubiKey blinks, touch it to authorize the login.&quot; Huh?<p>Despite what Unicode wants you to believe, emojis are not &quot;plain text&quot; and translate poorly to professional workstation-based communication. They are difficult to type on a regular keyboard, are tedious to copy and paste, and don&#x27;t belong in other plain text contexts like data storage or CLI pipes. Additionally emojis render differently for different users so you never truly know what your CLI might be displaying.<p>[1] <a href="https:&#x2F;&#x2F;www.linuxtopia.org&#x2F;online_books&#x2F;programming_books&#x2F;art_of_unix_programming&#x2F;ch11s09.html" rel="nofollow">https:&#x2F;&#x2F;www.linuxtopia.org&#x2F;online_books&#x2F;programming_books&#x2F;ar...</a>

Thank you! I&#x27;m working on the cli for <a href="https:&#x2F;&#x2F;www.postgrescompare.com" rel="nofollow">https:&#x2F;&#x2F;www.postgrescompare.com</a> and I really want to make it great!

Tell me to ignore man pages, and I will ignore everything else you say.<p>IMHO. YMMV.

What is the current best practice for making machine readable documentation of methods and options available in a CLI program? Similar to how OpenAPI works for RESTful services.

Beautiful website. Love that it respects system theme.

There&#x27;s some excellent content here. Unfortunately it is hidden behind an excessively wordy document. You should consider bringing in a ruthless editor to cut this down to about a quarter of it&#x27;s current length.

As for consistency between programs, that&#x27;s what vim keys accomplish for keymap. I used to be skeptical about these despite being a vim user. But viewed as a way to make programs more consistent, it&#x27;s good.

I think we should abolish different prefixes for short&#x2F;long flags except for core POSIX programs (like ls, cp, rm, mkdir, etc.) In other words, &quot;-flag&quot; should be interchangeable with &quot;-flag&quot;. The ONLY reason I can think of why you would not recognize &quot;-flag&quot; as equal to &quot;--flag&quot; is because you want to recognize it as &quot;-f -l -a -g&quot;, which makes sense for programs like ls, but for 99% of newer programs, don’t do it. Just make &quot;-flag&quot; and &quot;--flag&quot; equivalent.