Hello 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 t…
CLI Guidelines – A guide to help you write better command-line programs
81–90 of 217 posts
Re: CLI Guidelines – A guide to help you write better command-line programs
#82> "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.
I 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.
Re: CLI Guidelines – A guide to help you write better command-line programs
#83I 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. Ju…
Thing 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.)
I agree for the general case: typing commands in a terminal. But I often use long flags in scripts to improve readability.
Re: CLI Guidelines – A guide to help you write better command-line programs
#84Hello 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 t…
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-Profe...
The book is also online for free:
Command Line Options: http://www.catb.org/~esr/writings/taoup/html/ch10s05.html
User Interface Design Patterns: 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/
Re: CLI Guidelines – A guide to help you write better command-line programs
#85Earlier quoted context omitted.
I 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: comma…
Your 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.
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` )
Re: CLI Guidelines – A guide to help you write better command-line programs
#86It'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.
Re: CLI Guidelines – A guide to help you write better command-line programs
#87If 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.
Re: CLI Guidelines – A guide to help you write better command-line programs
#88Re: CLI Guidelines – A guide to help you write better command-line programs
#89My 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 dangerou…
Re: CLI Guidelines – A guide to help you write better command-line programs
#90Why are the font sizes so huge? The computed font size is 30px, compared to 12px for hn.