41 ms·
CLI Guidelines – A guide to help you write better command-line programs
- bfirsh 6y agoHello HN! We’re Ben, Aanand, Carl, Eva, and Mark, and we made the Command Line Interface Guidelines. 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 really good, so I looked for some design guides or best practices. Turns out, nothing substantial had been published since the 1980s. 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. 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. 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] [0] https://replicate.ai/ https://replicate.ai/ [1] https://smallstep.com/blog/the-poetics-of-cli-command-names/ https://smallstep.com/blog/the-poetics-of-cli-command-names/ [2] https://github.com/cli-guidelines/cli-guidelines https://github.com/cli-guidelines/cli-guidelines [3] https://discord.gg/EbAW5rUCkE https://discord.gg/EbAW5rUCkE
- raywu 6y agoThanks for these resources! Definitely relate. CLI is the original chatbot
- ucarion 6y agoSince you bring up Docker, this little behavior has always baffled me: $ docker image ls -h Flag shorthand -h has been deprecated, please use --help But: $ docker image -h ls Flag shorthand -h has been deprecated, please use --help Flag shorthand -h has been deprecated, please use --help Flag shorthand -h has been deprecated, please use --help What's up with that? I'm guessing cobra nonsense, because everyone ends up wrapping cobra's weird API differently...
- codetrotter 6y agoLooks like it wants you to type --help, not -h. Still weird though, since -h is indeed a very very common shorthand used in many commands.
- whelming_wave 6y agoI know you're talking about how it's repeated three times, but something else here really bothers me. I understand if they're deprecating it because they plan to replace it with something else, but if they don't then I'll be pretty disappointed. From their docs, it looks like some of their other subcommands have shorthands which conflict with `-h'? Fine, I guess, but that just means when `-h' does work it'll shoot people in the foot with that other behavior. Software that clearly knows what I want, but refuses to, annoys me so much. For example, $ python3 Python 3.9.0 (default, Dec 2 2020, 10:34:08) [Clang 12.0.0 (clang-1200.0.32.27)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> quit Use quit() or Ctrl-D (i.e. EOF) to exit because they added `quit' as a top level variable with a `__str__' defined which returns that string. Do anything else! Make the `__str__' definition quit the program or something, test if it's being run at the top level in the CLI and quit, special case the CLI input so if only `quit' is entered, it quits. Heck, maybe just prefill the `quit()' on the next line so I just have to hit return. Do anything but instruct me to do what you should have done in the first place.
- resonantjacket5 6y agoI mean if you did that how would you access 'quit' if it is defined? It's a bit more complicated than it seems. Though I get your general point.
- cle 6y agoYou just access it, it's just a normal variable. $ python3 Python 3.8.6 (default, Nov 18 2020, 23:56:33) [GCC 9.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> quit Use quit() or Ctrl-D (i.e. EOF) to exit >>> q = quit >>> quit = "foo" >>> quit 'foo' >>> quit() Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'str' object is not callable >>> q() $
- uhoh-itsmaciek 6y agoThis is great, thank you! Under pagers, maybe add a note to respect PAGER if set? I prefer relying on terminal scrollback in some situations, and e.g. in psql often set PAGER=cat. Git respects this, too.
- swyx 6y agoyou're not the only ones who care! I've been collecting CLI design thoughts and nodejs utilities for a couple years: https://github.com/sw-yx/cli-cheatsheet/blob/master/README.md#cli-design-thinking https://github.com/sw-yx/cli-cheatsheet/blob/master/README.m... just added yours!
- abathur 6y agoThanks for writing! I haven't had a chance to read it yet, but I'm always looking for new opinions here. Looking forward to going through it :)
- jdporter 6y agoHit us up on Twitter. Eh, I think not. The "commands" I create are, most often, small tools for my own use, so I don't worry about making the names short. I always try to make the name a verb, or include a verb, e.g. "fetchbookmarks", "deleteduplicates"; one exception would be in the case of converters, in which case "convert" is implicit, e.g. "csv2xml" or whatever; and there may be other cases where the verb is implied. The Huffman Coding is important, though, and I have made some tools I use a lot, so I gave them short names. I use gvim a lot, and the wrapper I wrote for it (which does smart finding - it will load foo.cpp wherever it is under your cwd, as long as there's only one) I named g. I don't expect to distribute this tool, so I don't care. :-)
- pwg 6y agoI did not see a personal pet-peeve of mine: If a user of your CLI tool has explicitly requested the built-in help text via --help (or an equivalent switch that requests help) then that help text shall be output on stdout. It always peeves me to do: command --help | less only to find that the explicit request for help (the --help switch) has output the help text on stderr, and I then have to redo the invocation: command --help 2>&1 | less to cause the help text to actually be piped into less.
- throwaway201103 6y agoYour CLI should also have a man page, installed in the standard way. IMO, -? or --help should be fairly terse, ideally one screenful or less. More complete documentation should go in the man page. Edit: wrote this before I read "Don’t bother with man pages." Strongly disagree. Relying on web docs leaves your users in the lurch if they are working on a system with no external network.
- gumby 6y ago> "Don’t bother with man pages." Strongly disagree. Me too. I don’t want to jump to a different program, plus man pages are greppable. And you want the man pages that apply to the machine you’re using (versions, etc) — especially important when you’re using a remote machine (think how common then idiom is to do `ssh foo man blah|less` )
- btschaegg 6y agoWhile I regularly rely on `man` (and would agree with you for systems that have it), I'd also like to add that you should consider people on other systems, as well. I'm still stuck on Windows for work, and e.g. the way Git (at least the Windows version from git-scm.org) handles this is problematic. Something like `git --help` will open the URL to a help page (that also takes ages to load) in the browser. Manpages don't exist and there is no useful substitute. And this in a Git distribution that ships with its own GNU environment (MSYS2). And then, there's Git LFS, for which I haven't even found a working help command yet. While the original idea might have been that the terminal way of looking things up is too confusing for Windows users (which I find ironic, given that said users installed a terminal program), I find it still makes Git even more arcane on this platform. Edit: Coming back to `man`: Git is in the useful position of shipping their own GNU environment. That means, they could still introduce manpages. Other, small CLI utilities usually don't have that luxury. In those cases, some kind of access to the information in the manpage would still be very handy, even if it is just in `tool --help`.
- 0x445442 6y agoIt always seems to fall through the cracks in these discussions, maybe because there's not a lot of folks who run the distro, but Gentoo has very nice command line tools.
- remexre 6y agoDo you mean emerge et al? I've been running Gentoo on my main machine for >1 year now, and I'm still having to check the manpage for flags constantly... I guess I wish that it was more explicitly "subcommandy."
- chubot 6y agoTurns out, nothing substantial had been published since the 1980s. The best reference I've found on this is The Art of Unix Programming, which was published in 2003: https://www.amazon.com/UNIX-Programming-Addison-Wesley-Professional-Computng/dp/0131429019 https://www.amazon.com/UNIX-Programming-Addison-Wesley-Profe... The book is also online for free: Command Line Options: http://www.catb.org/~esr/writings/taoup/html/ch10s05.html http://www.catb.org/~esr/writings/taoup/html/ch10s05.html User Interface Design Patterns: http://www.catb.org/~esr/writings/taoup/html/ch11s06.html http://www.catb.org/~esr/writings/taoup/html/ch11s06.html Still it's nice to see this knowledge circulating! Joel Spolsky's 2003 review of this book: https://www.joelonsoftware.com/2003/12/14/biculturalism/ https://www.joelonsoftware.com/2003/12/14/biculturalism/
- veddox 6y agoAn excellent book! It was one of the first software development books I read and still shapes my programming style. I probably ought to read it again though, I suspect I would understand a lot of it a lot better now...
- enriquto 6y agoMost of what you say is useful common sense, but the bit about not bothering with manpages is plain evil. If anything, the man page must be written before the program interface!
- alkonaut 6y agoIs there a usage statistic for how often man pages are read? I violently agreed with the article here. There are zero times I wouldn’t rather switch to a browser. Even if I had to dig up my phone from my pocket and search for help there, I’d much rather do that. Also, more and more tools are cross platform and man pages aren’t a thing on windows (are they?).
- enriquto 6y agoI don't have any statistic, but I use them all the time. Under vim's default configuration, manpages are a single keypress away. If you press "K", vim opens a window with the manpage of the word under the cursor. It happens instantaneously, and it uses the same font and color scheme than your code. I would really hate it if it opened a browser!
- mulmen 6y agoReally? So if I make a man page for my CLI tool you would assault me physically? You should take your own description of your beliefs as a red flag to reassess them. I use a few tools that don’t have man pages and I always find it jarring that I have to leave the CLI to get some basic usage info. There is already tooling to generate manages and online/html docs from a single source. Reasonable thing seems to be “do both”. I’m not persuaded by “Windows is leaking.”
- alkonaut 6y ago> So if I make a man page for my CLI tool you would assault me physically? What, and ... what?
- 6y ago
- airstrike 6y agoHey, I can't zoom in or out on the website... The font always stays at the same huge size. Using Firefox on Windows
- gruez 6y agoWhy are the font sizes so huge? The computed font size is 30px, compared to 12px for hn.
- airstrike 6y agoAlso the font size is hardcoded so zooming in does nothing other than making scrolling terrible
- johnisgood 6y agoIt works for me. I can decrease the font size the usual way.
- airstrike 6y agoStill doesn't work for me in Firefox on Windows
- johnisgood 6y agoCheck the shortcut for it and try. Does it work? Weird. I am using a Chrome-based browser though.
- airstrike 6y agoI tried it, but that doesn't work either...
- matt_kantor 6y agohttps://github.com/cli-guidelines/cli-guidelines/issues/36 https://github.com/cli-guidelines/cli-guidelines/issues/36
- macintux 6y agoThanks, this is sorely needed. Looking forward to taking time to dig more deeply into it.
- EE84M3i 6y agoIt's kind of crazy that we still don't have a standard computer readable way for a program to describe it'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.
- mmalone 6y agoYea, like, imagine if posix pipes and command-line flags could be typed.
- vageli 6y agoPowershell offers this I believe.
- mmalone 6y agoYep. Not perfect... type systems have come a long way since PowerShell did it. But it's a good start. Look at stuff like PowerShell secure strings for an example of the sort of neat stuff you can do.
- ChrisSD 6y agoNuShell is also attempting this. Both are cross platform. https://github.com/nushell/nushell https://github.com/nushell/nushell
- _underfl0w_ 6y agoThanks for mentioning this! It looks super interesting, but I hadn't heard of it before.
- jmmv 6y agoThat's right. I recently wrote on this topic: https://jmmv.dev/2020/10/powershell-cmdlet-params.html https://jmmv.dev/2020/10/powershell-cmdlet-params.html
- 6y ago
- jmmv 6y agoHah. This is a topic that'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. But... here is a series of blog posts in which I covered similar themes years ago: https://jmmv.dev/series.html#CLI%20design https://jmmv.dev/series.html#CLI%20design And here is another single post that touches upon a single guideline I came across while skimming through the text: https://jmmv.dev/2020/08/config-files-vs-directories.html https://jmmv.dev/2020/08/config-files-vs-directories.html . It might be helpful in providing more details about the _whys_ behind each guideline. Lastly, I'll also mention the "Producing open source software" book by Karl Fogel, which provides a lot of useful advice too, especially on how to ship the tools: https://producingoss.com/ https://producingoss.com/
- mdoms 6y agoThere'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's current length.
- actuallyalys 6y agoWhat do you think is wordy? It's detailed, but as an occasional editor, I'm not seeing much wordiness. It also makes good use of headers and bolding so readers can skim and skip if they want. There's definitely imagery, history, and definitions that technically could be cut, but the guidelines would be poorer for it—especially for people with less familiarity with the commandline. I do think they should consider releasing a cheat sheet alongside the full document with just the bolded guidelines.
- kitotik 6y agoThis is a great resource, thanks for the effort. 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. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…
- mmalone 6y agoThey're not saying you shouldn't provide command-line help. Just that you should deliver them through a `help` subcommand and/or through a `--help` flag (like `git` does) because people don't find man pages and because man pages don't work on every platform.
- kitotik 6y agoRight. I still prefer terse help text from the command line, and more in-depth in the man pages. I find commands with copious -h output and having to pipe that into a pager or using scroll back a far worse UX than just opening up a man page that’s easily searchable / scrollable.
- mmalone 6y agoYea that's reasonable, but there are pros and cons and it's also definitely an opinion :). I don't see the problem with piping help text through a pager (that's literally all `man` is doing). Alternatively, a tool can use a pager automatically (as `git help ...` does). So `man` isn't required to have a pager. Whether you should use a pager by default is a different argument. That said, I find pagers annoying because it's hard to switch back and forth between typing a command and the docs. That's way easier to do with scrollback. Although someone in this comment thread also mentioned the `PAGER` env var, and that you can set `PAGER=cat`, which is a good pro-tip. So, TIL. Still, if you're concerned with command-line ergonomics for a broad audience I think there are more people that either 1) know how to `| less` or 2) prefer or don't care about a pager than people who are gonna automatically just know they can do `PAGER=cat man <some-subcommand-of-my-cli-tool>`. Plus, there's still the cross-platform argument. Oh, and OP doesn't mention this, but man pages also complicate install, uninstall, versioning, and having multiple versions of a tool installed simultaneously. Built-in help is obviously just works and is distributed with the standalone binary. To use man pages you have to place additional artifacts on the system and make sure they're managed correctly (e.g., versioned). It's additional complexity with basically zero benefit. So yea. Seems like, as a rule, their guidance is reasonable. I don't see a lot of benefit to using man pages other than "because that's how it's always been done".
- zokier 6y ago> The command line of the past was machine-first > Traditionally, UNIX commands were written under the assumption they were going to be used primarily by other programs 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/system oriented mainframes of IBM etc)
- nrclark 6y agoI'd say say there's some truth to it, but maybe in an accidental way. Shell scripts have been part of UNIX since day 1. A lot of early UNIX commands were implemented as scripts, and shell was always intended to be one of the main extension mechanisms for users. Scripting is fundamentally based on the assumption that a script will run various commands, glued together in a user-specified way. So it's true to say that most early UNIX commands were designed to be useful in a script, which implies that they were designed for use by programs. Maybe not designed _exclusively_ for use by programs, but definitely an important design consideration.
- reaperducer 6y agoMy recollection is that non-programmers followed the instructions in the binder, which told them how to log in, and then how to start the program they needed. Very basic stuff. Actual commands were the province of programmers.
- brownjohnf 6y agoI think the common terseness of many of the core suite of original unix tools actually reflects a strong focus on human, not machine, ergonomics. I still appreciate the speed and ease of typing them, and like many other aspects of the CLI, it's optimized for users who know it well and use it heavily. Once you're familiar with the names, it's not challenging to remove that mv = move, wc = wordcount, etc. Terminals of the era also still actually printed mechanically, so keeping command length short was a major ergonomic win for round trip speed. As a sibling comment mentions, these commands were (are) commonly composed into scripts. As the name implies, however, a script is just a playbook for a series of commands to run. Given the terminals of the era, I'm sure short commands/variables/etc. were appreciated in scripts as well, but it seems to me that the primary motivation for optimizing input speed would be the use of these commands in an interactive environment. A few examples of these core short program names: ls, cat, cp, rm, wc, uniq, cmp, diff, od, dd, tail, tr, etc.
- dllthomas 6y agoLoving this! As a nit: > Let the user escape. Make it clear how to get out. (Don’t do what vim does.) If your program hangs on network I/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. 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'm aware, there'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're on the right track or that there's even a track to be on. Also, vim is (in part) a wrapper around program execution.
- kevincox 6y agoI agree, if you press Ctrl-C vim (with default settings) literally tells you how to quit. `\n~` in SSH is completely unrecoverable.
- Aeolun 6y agoIf you are already using SSH in a situation where ‘exit’ doesn’t work, it becomes more reasonable to assume the user will know.
- dllthomas 6y agoI don't understand what you're saying here; could you expand a bit?
- matt_kantor 6y agoI'm not who you replied to, but I hardly ever need to use tilde escape sequences to quit ssh. I just terminate the session from inside itself with the `exit` command.
- 6y ago
- dllthomas 6y ago> Which means O_O and OwO are the only emoticons that are also valid environment variable names. O_o
- klodolph 6y agoI think we should abolish different prefixes for short/long flags except for core POSIX programs (like ls, cp, rm, mkdir, etc.) In other words, "-flag" should be interchangeable with "-flag". The ONLY reason I can think of why you would not recognize "-flag" as equal to "--flag" is because you want to recognize it as "-f -l -a -g", which makes sense for programs like ls, but for 99% of newer programs, don’t do it. Just make "-flag" and "--flag" equivalent.
- attractivechaos 6y ago> for 99% of newer programs, don’t do it The majority of recent tools in my circle follow this Unix convention. That is a natural result when you use getopt_long().
- klodolph 6y agoRight, "don't do it" is imperative mood, not indicative mood. If it were indicative mood, the clause would need a subject but in a casual internet forum I can see why people would omit the subject anyway ¯\_(ツ)_/¯ This is one of the reasons why I don't use getopt_long() -- I don't WANT short flags to be combined, for most commands I write. Fortunately, getopt_long() is one of those library functions that is truly trivial to reimplement and not something that has arcane behavior or edge cases.
- trasz 6y agoThing is, being able to concatenate options together saves a lot of typing. (And honestly, —long-flags are rarely useful in practice. Unless you have no man page to figure out what the single letter options do.)
- RMPR 6y ago> honestly, —long-flags are rarely useful in practice. Unless you have no man page to figure out what the single letter options do I agree for the general case: typing commands in a terminal. But I often use long flags in scripts to improve readability.
- postgrescompare 6y agoThank you! I'm working on the cli for https://www.postgrescompare.com https://www.postgrescompare.com and I really want to make it great!
- alcover 6y agoNice initiative! A few remarks : - the intro text is way too long - you contradict yourselves about stdout : `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.`
- thomasbacklund 6y agoNice read, makes me happy to see people invest in CLI. "Humans first"... How about "Humans with Tools first" ? :) 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'ing over it.. Just saying :) I would very much recommend The Art of UNIX programming, by Eric S. Raymond [0] 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). Going full termie is the best choice I've made, thanks for a good read! \o [0] http://www.catb.org/esr/writings/taoup/html/ http://www.catb.org/esr/writings/taoup/html/ (There is a PDF available somewhere too) [1] https://space.sh/ https://space.sh/
- Aeolun 6y agoIt would be nice to see an example of space.sh usage somewhere on the landing page. I was intrigued by “through 10 firewalls” but not quite enough to go to the documentation and look it up.
- thomasbacklund 6y agoHey :) Thanks for the tip! Yes, upping the site with articles and examples is on the TODO :) In the SSH module doc [0] there are a few examples, such as: space -m ssh /ssh/ -e SSHHOST=jump1.example.com,jump2.example.com,jump3.example.com,destination.example.com -e SSHCOMMAND="ls -l" One very fun feature is that you can tab auto-complete filenames and container names and also files inside container on a remote host: space -m ssh -e SSHHOST=1.2.3.4 -e SSHPORT=2233 -e SSHUSER=rabbit /wrap/ -m docker /wrap_exec/ -e DOCKERCONTAINER=[tab tab] Then: space -m ssh -e SSHHOST=1.2.3.4 -e SSHPORT=2233 -e SSHUSER=rabbit /wrap/ -m docker /wrap_exec/ -e DOCKERCONTAINER=something -m file /cat/ -e file=/home/[tab tab] Note that server jumping (over firewalls) is perfectly viable in the last example too, by adding more hosts (comma separated). Note that it can be important to balance host names to user names (see the doc [0]). In the examples space wraps module functionality where the last module file is the one finally running inside the container, wrapped first by the `ssh` module then the `docker` module. It is totally agent-less so nothing is uploaded to the server, it's just like SSHing in and running commands. If you add the `-d` flag to space it will dump the script to output, which you can save to a .sh file and run later (without needing space.sh at all). Space it self requires bash, but the output runs with POSIX shells, so it also works with dash/ash/busybox, etc which is good because servers/containers often doesn't come with bash, but simpler ash/dash instead. Thanks for showing interest, this makes me keen on pushing a few fixes and updates I have pending. Let me know if it doesn't work and I'll fix that :) [0] https://space.sh/gitlab.com/space-sh/ssh/doc/master/examples/ https://space.sh/gitlab.com/space-sh/ssh/doc/master/examples...
- tpoacher 6y ago> "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." I couldn't disagree more.
- Aeolun 6y agoI really do not enjoy reading man pages though. tldr or —help is much more likely to contain the info I want on the first screen.
- trasz 6y agoThat is usually a sign of functionality bloat, not a problem with man pages as such.
- t0astbread 6y agoThat's why I think both are important: -h/--help for a short description, man pages for more detailed "handbooks". There Ideally there would also be a "compatibility" rendering of man pages bundled for systems like Windows that don't have anything like man.
- brabel 6y agoYou couldn't disagree that "not enough people use man pages"? Do you have a source for that belief? It's really weird to me that a few people here seem to really like their man page... when you can just do `cmd --help` and it works in pretty much any program, and you can visit the website for in-depth information.
- alpaca128 6y agoWhy would you not want access to a program's documentation within its own environment? Requiring a working internet connection and a web browser just to look up plain text docs sounds a bit like needing a fax machine to receive a receipt for online payments. `cmd --help` is usually only a shortened version and rarely includes notes about specific behaviour, for example. Man pages are very comprehensive and can be navigated without needing to switch between windows and different input methods.
- woodruffw 6y agoThese are some pretty good guidelines! Many thanks to the authors for writing them up. Some nitpicks (what would HN be without nitpicks?): > If your command is expecting to have something piped to it and stdin is an interactive terminal, display help immediately and quit. I disagree with this advice: being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm that the authors mention above. Commands that silently block on `stdin` are frustrating, but the right solution is to check `isatty(3)` and print an informational message rather than killing the program entirely. > Check general-purpose environment variables for configuration values when possible 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. > Don’t bother with man pages. Please do 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/ReST/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. [1]: https://github.com/rtomayko/ronn https://github.com/rtomayko/ronn [2]: https://pandoc.org/ https://pandoc.org/ [3]: https://www.sphinx-doc.org/en/1.4/man/sphinx-build.html https://www.sphinx-doc.org/en/1.4/man/sphinx-build.html
- hamburglar 6y ago> being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm that the authors mention above. Commands that silently block on `stdin` are frustrating, but the right solution is to check `isatty(3)` and print an informational message rather than killing the program entirely This was the one thing I was coming here to nitpick. I use the "blocking stdin" behavior regularly to pipe copy/pasted text through various commands (various openssl subcommands, for example) and would be very annoyed if a program decided on its own that I shouldn't be doing that. At most, it should print a message like "Reading from stdin..." or something on stderr, but even that seems like introducing noise to hold the hands of people who don't understand the pipe paradigm.
- matt_kantor 6y ago
- pdkl95 6y agoA few additions to these recommendations: > Show full help when -h and --help is passed It is also a good idea to support --version $ 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 <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. > Use standard names for flags, if there is a standard. In the interest of consistency across tools, I recommend consulting the Table of Long Options from the GNU Coding Standards. https://www.gnu.org/prep/standards/html_node/Option-Table.html https://www.gnu.org/prep/standards/html_node/Option-Table.ht... Some long options that are particularly helpful, when appropriate: ‘dry-run’ ‘-n’ in make. ‘null’ ‘-0’ in xargs. Also, options that increase safety: 'no-clobber' ‘-n’ in mv # do not overwrite an existing file 'overwrite' ‘-c’ in unshar # even better than --no-clobber, require explicit # permission before overwriting existing files edit: Never try to be "smart" or "magic" and guess what the user intended! DWIM can appear useful at first, but we've known for a long time that DWIM behavior is dangerous[1]. [1] https://news.ycombinator.com/item?id=15628014 https://news.ycombinator.com/item?id=15628014
- Aeolun 6y agoDepends on what you are doing. If it’s just a transformation or display of data, there’s no reason not to do what the user meant.
- brandmeyer 6y agoGreat doc! I disagree about abandoning manual pages. I always reach for `man foo` even before `foo --help`. 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.
- zelly 6y agoMy advice as a user of CLI: - no emojis please, ever - if you want to make it look nice, use ANSI escape codes for color rather than emojis. even then, don't use color alone to convey meaning because it will most likely get destroyed by whatever you're piping it to. - please take the time to write detailed man pages, not just a "--help" screen - implement "did you mean?" for typos (git style) and potentially dangerous commands - separate the interface into a tree of subcommands (Go/Docker/AWS style) rather than a flat assortment of flags - if you are displaying tabular data, present an ncurses interface - (extremely important) shell completion for bash and zsh
- deleted 6y ago[deleted]
- jorgebucaran 6y agoAnd Fish!
- fiddlerwoaroof 6y agogit’s behavior is really nice: any program on $PATH named `git-foo` can be accessed as a sub command `git foo`. I’ve personally taken this a step further, and wrapped git in a shell function so that `git cd bar` navigates to the directory `bar` relative to the repository root.
- brabel 6y ago> - no emojis please, ever Why not? Do you also don't want to see icons in GUIs?
- alpaca128 6y agoIcons in GUIs are commonly used for interactive elements. Most CLI tools are not interactive, they just produce some output and the user expects that output to be easy to parse and compatible with as many terminals as possible. You can easily output tables, bullet lists and many other things just with basic symbols supported everywhere. If your CLI program requires installing fontawesome or breaks in a terminal multiplexer etc. I'm probably not going to use it.
- 0x445442 6y agoThe command line, in terms of the terminal emulator, really needs to evolve to more of a Meta-X mini-buffer pattern. 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. On one end you've got a set of people doing heroic designs in the terminal with all variety of UTF-8 characters. On the other end you've got things like Jupiter Notebook. What I'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.
- hollerith 6y agoThe software I will use to invoke your command immediately send EOF to your process's stdin. Almost all traditional Unix command do something sensible in response. "mv -i" for example, refrains from moving anything. The software I prefer to use to run your command has no provision for your command's trying to engage me in a conversation. 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 "y". But your command is probably not important enough for me to bother running it in Terminal.app. 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's arguments and the command's environment variables till I get it right. 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's terminal works, the software I will use to invoke your command does not automatically scroll to the bottom of the process's output: the window does not scroll unless I tell it to scroll, e.g., by hitting the page-down key.) lynx was my primary browser for about 10 years, so it is not like I am ignorant of "full screen" terminal interfaces; I am just weary of them.
- smithza 6y agoI find it very interesting that the sources and "further readings" 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.
- ashneo76 6y agoYes. 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.
- johnisgood 6y agoYeah. The direction we are taking is nuts. Is it because of incompetent web developers? For everybody: do not take it personally.
- ngcc_hk 6y agoQuit 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.
- inetknght 6y agoCould you make the site usable without javascript? Right now there's a sidebar with a transparency that overlaps half of the paragraphs.
- blt 6y agoThis is a great resource. I will return to read it closely next time I am designing a CLI. One thing that puzzled me: `git push` is given as an example of the principle "If you change state, tell the user". Its output is: $ git push Enumerating objects: 18, done. Counting objects: 100% (18/18), done. Delta compression using up to 8 threads Compressing objects: 100% (10/10), done. Writing objects: 100% (10/10), 2.09 KiB | 2.09 MiB/s, done. Total 10 (delta 8), reused 0 (delta 0), pack-reused 0 remote: Resolving deltas: 100% (8/8), completed with 8 local objects. To github.com:replicate/replicate.git + 6c22c90...a2a5217 bfirsh/fix-delete -> bfirsh/fix-delete 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: $ git push Writing objects: 100% (10/10), 2.09 KiB | 2.09 MiB/s, done. Pushed 10 objects to github.com:replicate/replicate.git + 6c22c90...a2a5217 bfirsh/fix-delete -> bfirsh/fix-delete
- djrhails 6y agoI think the problem with this approach is when you start to utilise large (normally mono) repos the earlier stages can take significant time. Then you're in a condumdrum of if you make the loading more generic or have an input lag to get to "writing objects".
- account42 6y agoYou could have temporary progress information that (by default) gets overwritten when in an interactive terminal.
- sbr464 6y agoWhat 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.
- dspillett 6y agoWRT man pages: > and they don’t work on Windows My cygwin install says otherwise. And even if that were not the case I wouldn'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.
- johnisgood 6y agoThat, or MSYS2.
- b0rsuk 6y agoAs for consistency between programs, that'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's good.
- xeyownt 6y ago> Use a command-line argument parsing library where you can. > ... > Python: Click, Typer What's the problem with using the python standard library argparse? I would frown upon adding a dependency for such a core feature as argument parsing, unless it brings strong benefits. And even then, I'd recommend to use the standard lib and to switch to the other libs only when necessary.
- acabal 6y agoargparse is really good and it's built-in. I was also wondering why it wasn't listed as the default option for Python, let alone it not being mentioned at all.
- dxdm 6y agoI'd use click over argparse for the same reason I prefer the requests lib over built-ins for standard network communication: it smoothes out the rough edges, cuts down on boilerplate and makes the code easier to read, write and maintain.
- acabal 6y agoThis is a good resource with a lot of good points. But, > Display output on success, but keep it brief. Strong disagree. If everything went OK, or something is in progress, I don't need to be notified; it's distracting and makes me instinctively think something has gone wrong and needs my attention. The Art of Unix Programming got it right, "Silence is golden."[1] I'm disappointed that `git push` is their example of good CLI output, because I've truly hated git's entire CLI design and philosophy for years. Git'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's using delta compression using 8 threads? That it's counting objects? That it's compressing objects? That information is useless plumbing output that clutters and distracts for no purpose. Just do the work and keep quiet, with at most a progress bar for a long-running command--and even then it should be optional. If people really want chatty output, include an optional --verbose flag, or even levels of verbosity with -v, -vv, -vvv, etc. > Use symbols and emoji where it makes things clearer. Please, no. This is a fad right now and it's also really distracting. Symbols and emoji don'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 "Error" 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't all of those mean "Error"? 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 "When the YubiKey blinks, touch it to authorize the login." Huh? Despite what Unicode wants you to believe, emojis are not "plain text" 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'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. [1] https://www.linuxtopia.org/online_books/programming_books/art_of_unix_programming/ch11s09.html https://www.linuxtopia.org/online_books/programming_books/ar...
- deleted 6y ago[deleted]
- mybrid 6y agonpm 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't have '--no-color' and the binary characters will trip up diff and other tools that only work on text.
- whirlwin 6y agoThe 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
- johnisgood 6y agoI want both --help/-h and man pages!
- skavi 6y agoBeautiful website. Love that it respects system theme.
- bradknowles 6y agoTell me to ignore man pages, and I will ignore everything else you say. IMHO. YMMV.
- colanderman 6y ago> If your help text is long, pipe it through a pager. I disagree that this is a good practice. This prevents me from using my terminal's scrollback to read and/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'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. If I want to page the help output, I will pipe it to a pager myself. If the help text is really so unreasonably long that it's unsuitable for --help, hide it behind some other option that --help points me to. Git does this (effectively treating "-h" the way every other CLI treats "--help", and "--help" as a request to open a man page), and it's incredibly annoying, because no other CLI I use works this way, so it screws up my muscle memory in a way that impacts both my usage of Git and of everything else.
- alphachloride 6y agoI 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). In all honesty, I just really dislike emojis The guidelines were all helpful otherwise. It shows that I could only find one nitpick.
- alphachloride 6y ago^Like here. I put laugh-crying emojis ironically at the end but they were filtered out. Many terminals wouldn't do me this courtesy of shielding my eyes and instead regurgitate gibberish characters.
- account42 6y ago> Don’t bother with man pages. > If your help text is long, pipe it through a pager. > Use formatting in your help text. 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't just ignore standards and conventions because not all operating system agree on them. 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. > Use symbols and emoji where it makes things clearer. Eww. And the example is pretty bad too with a number of meaningless icons. > By default, don’t output information that’s only understandable by the creators of the software. 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't underestimate your user's abitlity to understand stuff. > Use a pager (e.g. less) if you are outputting a lot of text. > A good sensible set of options to use for less 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.
- GoblinSlayer 6y ago>“Abandon a standard when it is demonstrably harmful to productivity or user satisfaction.” — Jef Raskin, The Humane Interface Basically description of posix. Well, sure, it tries to solve an unsolvable problem, but still.