CLI Guidelines – A guide to help you write better command-line programs • Hacker News Board

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

#111

Post by tjoff » Sat, Dec 05, 2020, 10:18 AM UTC

whelming_wave wrote: post #34

ucarion wrote: post #8

Earlier quoted context omitted.

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…

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

I don't agree. Fail fast fail hard or you deliberately lie and confuse your users.

If I make a mistake - tell me. If you allow me to do it slightly wrong then suddenly in my universe there is no consistency between commands and that is way worse than being told what I did wrong.

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

#112

Post by btschaegg » Sat, Dec 05, 2020, 11:03 AM UTC

throwaway201103 wrote: post #73

pwg wrote: 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.

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

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

#113

Post by alpaca128 » Sat, Dec 05, 2020, 11:04 AM UTC

brabel wrote: post #105

zelly wrote: 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…

> - no emojis please, ever Why not? Do you also don't want to see icons in GUIs?

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

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

#114

Post by enriquto » Sat, Dec 05, 2020, 11:05 AM UTC

bfirsh wrote: 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…

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!

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

#115

Post by b0rsuk » Sat, Dec 05, 2020, 11:06 AM UTC

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

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

#116

Post by alpaca128 » Sat, Dec 05, 2020, 11:14 AM UTC

brownjohnf wrote: post #63

zokier wrote: post #24

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

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

I find it interesting how GUI and CLI drift apart so far in this area. Powerful GUI software for specialised tasks is often overloaded with buttons and toolbars everywhere because the user needs to be able to click them. The terminal is the complete opposite, instead of clicking through menus to find the right option(or use a ton of keyboard shortcuts) you have to know what to type. But it's also very efficient and flexible, and in exchange for more difficult discoverability of features it circumvents menus completely.

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

#117

Post by enriquto » Sat, Dec 05, 2020, 11:16 AM UTC

lokedhs wrote: post #108

zelly wrote: 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…

No, please don't use escape codes in your output. Use the library that is designed for this purpose: terminfo. Explicit escape codes is problematic when using any terminal that isnt' fully compatible with the xterm control codes, and doesn't allow me to turn those codes off by setting TERM to dumb. Far too many times have I redirected output from a program to a file only be be bombarded with escape codes, breaking gr…

> Not to mention the fact that using terminfo is much easier than manually outputting the control codes.

Strong disagree. I already know many control codes by heart and can write them inside the printf strings. For terminfo, I have to include it, link against it, call bizarre functions, and then the library must be available at compile time, at runtime, and also the shared files at runtime. I have seen each one of these constraints fail for different reasons, and now I simply ignore the existence of terminfo. It is better to not abuse color, make color optional, but if you need some color you just use the xterm control codes that work everywhere.

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

#118

Post by antientropic » Sat, Dec 05, 2020, 11:18 AM UTC

lokedhs wrote: post #108

zelly wrote: 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…

No, please don't use escape codes in your output. Use the library that is designed for this purpose: terminfo. Explicit escape codes is problematic when using any terminal that isnt' fully compatible with the xterm control codes, and doesn't allow me to turn those codes off by setting TERM to dumb. Far too many times have I redirected output from a program to a file only be be bombarded with escape codes, breaking gr…

No, don't bother with terminfo. It just gives you support for terminals that haven't been in use since the Apollo program. Nowadays it's perfectly fine to use ANSI escapes directly, which are, after all, a standard.

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

#119

Post by alpaca128 » Sat, Dec 05, 2020, 11:34 AM UTC

brabel wrote: post #107

tpoacher wrote: post #55

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

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

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

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

#120

Post by scbrg » Sat, Dec 05, 2020, 11:39 AM UTC

brabel wrote: post #105

zelly wrote: 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…

> - no emojis please, ever Why not? Do you also don't want to see icons in GUIs?

Personally, I don't. I quite like things to be text, because text can be understood. Icons can be... learned, I suppose, but then they tend to be inconsistent between apps and even change depending on themes and whatnot - so in general, it's mostly like playing a game of Memory where someone keeps shuffling the pieces.

But the main reason not to use emojis would be that you have no idea how they'll look to the user. I tried to paste the example output from yubikey-agent into my terminal, and all I got was a bunch of differently sized squares. Very informative...