Live data from Hacker News

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

clig.dev

81–90 of 217 posts

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

#81
post #2

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…

It 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.

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

#82
post #58

> "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.

That'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.

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

#83
post #61

I 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.)

> 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

#84
post #2

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…

Turns 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-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

#85
post #62

Earlier 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.

> "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` )

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

#86
post #6

It'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.

it's not that we don't have standard(s); it's the problem of adoption.

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

#87
The 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.

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

#88
I 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.

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

#89
post #69

My 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…

And Fish!
Post reply on HN