7 ms·

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]

by bfirsh 6y ago

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 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 ago
Thanks for these resources! Definitely relate. CLI is the original chatbot
ucarion 6y ago
Since 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 ago
  Looks 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 ago
  I 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 ago
    I 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 ago
      You 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 ago
This 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 ago
you'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 ago
Thanks 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 ago
Hit 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 ago
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: command --help 2>&1 | less to cause the help text to actually be piped into less.
- throwaway201103 6y ago
  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.
  - 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 ago
    While 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 ago
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.
- remexre 6y ago
  Do 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 ago
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-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 ago
  An 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 ago
Most 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 ago
  Is 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 ago
    I 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 ago
    Really? 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 ago
Hey, I can't zoom in or out on the website... The font always stays at the same huge size. Using Firefox on Windows

by bfirsh 6y ago

raywu 6y ago

Thanks for these resources! Definitely relate. CLI is the original chatbot

ucarion 6y ago

Since 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 ago
Looks 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 ago
I 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 ago
  I 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 ago
    You 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 ago

This 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 ago

you'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 ago

Thanks 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 ago

Hit 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 ago

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: command --help 2>&1 | less to cause the help text to actually be piped into less.

throwaway201103 6y ago
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.
- 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 ago
  While 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 ago

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.

remexre 6y ago
Do 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 ago

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-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 ago
An 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 ago

Most 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 ago
Is 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 ago
  I 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 ago
  Really? 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 ago

Hey, I can't zoom in or out on the website... The font always stays at the same huge size. Using Firefox on Windows