HACKER Q&A
📣 pseufaux

Best Practices for CLI sub-command, argument, option, flag, etc. design?


I am looking for any insights or resources on best practices surrounding cli application design. There is a lot of variance out there in how tools use sub-commands, arguments, options, flags, etc. Some tools like git use nested sub-commands to distinguish between operations, while others like curl use options to accomplish the same purpose. Sometimes flags are mnemonic, but many times that's not possible because of the sheer number of flags. Some tools keep "long option" names short ("--list") while others may have multiple words ("--list-software-updates"). There's more but, I'll stop now to keep from rambling.

I did a cursory search and found a few seemingly universal guidelines, though none of them spoke to how arguments and options should be used.

* use stdout and stderr appropriately (i.e., don't write messages to the user to stdout) * use exit codes to indicate success / failure cases * ensure output is consistent and easily parsed by other cli tools

What do you like? What do you hate? I would love to hear your thoughts on what style choices make for a more ergonomic cli tool.

  👤 eesmith Accepted Answer ✓
I like nested sub-commands. If you use Python, I think click is a good tool.

Things like '--list' vs '--list-software-updates' depends on what the tool does. You might have '--list-formats', '--list-authors', and more, in which case a single '--list' might not be meaningful (unless it's clearly obvious what it will list).

It also depends on a lot on how the subcommands work together. You might have --define to be clear, but have it be used so often that your users will want '-d' because 1) it saves time, and 2) they use it so often they don't have a problem remembering what it means.

I can't think of any guides off-hand.

It's a category of UI design, so many UI/UX techniques could be applied to the task. That thought lead me to search for "command-line" and "UX" together, finding things like:

"3 Commandments for CLI Design" - https://medium.com/relay-sh/command-line-ux-in-2020-e537018e...

"Command Line User Experience" - https://techblog.cisco.com/blog/cli-ux

"Designing Great Command-Line User Experiences" - https://www.juliandunn.net/2016/08/09/designing-great-comman...

I think those have enough to get you started, and to help you find related resources.