Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

clig.dev

Post reply on HN
Print view View original

181–190 of 217 posts

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

#181

Post by sedatk »

pimlottc wrote: post #176
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…

THANK YOU. Showing the usage documentation when the user has explicitly asked for it /is not an error/.

Yes, but many apps show help text when incorrect arguments are provided so, it’s an error in those cases. The dev probably doesn’t want to bother with using different output channels for the same help text.

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

#182

Post by johnisgood »

airstrike wrote: post #174
johnisgood wrote: post #164

Earlier quoted context omitted.

It works for me. I can decrease the font size the usual way.

Still doesn't work for me in Firefox on Windows

Check the shortcut for it and try. Does it work? Weird. I am using a Chrome-based browser though.

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

#183

Post by klodolph »

gnubison wrote: post #171
klodolph wrote: post #126

Earlier quoted context omitted.

Yes, I agree… be consistent and avoid ambiguity. Combined short flags are the most ambiguous of all. Usage in practice would be split between -flag and --flag… so what? They shouldn’t mean different things, because it is too easy for humans to miss the extra -. And in the end, CLIs are for humans first.

> And in the end, CLIs are for humans first. I don't think that CLIs are more suited to either humans or computers. CLIs are flexible enough to be effectively used by both. > Usage in practice would be split between -flag and --flag. So what? Well, you're breaking everybody's expectations and many years of conventions by doing it. Saving one dash with every flag and losing the ability to combine short options is just…

> I don't think that CLIs are more suited to either humans or computers. CLIs are flexible enough to be effectively used by both.

Either a human is sitting at a terminal typing commands, or a human is sitting at a text editor writing a shell script, or a human is writing a program which runs other commands. In all cases, it's a bunch of strings pasted together and the computer can't typecheck it, so we need to make sure that the strings are readable by humans.

> Well, you're breaking everybody's expectations and many years of conventions by doing it. Saving one dash with every flag and losing the ability to combine short options is just not a good trade off.

If you've named your account on HN "gnubison", it's safe to say that you've got some biases. It might surprise you to know, then, that plenty of programs already don't let you combine short options, and that not everybody uses getopt_long or something compatible.

Combining short flags saves you a small amount of typing sometimes, but it adds extra confusion. So in general, I would say that most commands should not allow you to combine short flags.

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

#184

Post by enriquto »

alkonaut wrote: post #170
enriquto wrote: post #114

Earlier quoted context omitted.

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!

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

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!

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

#185

Post by solatic »

solatic wrote: post #180
nocman wrote: post #169

Earlier quoted context omitted.

For those on Linux you can do this with: f=$(mktemp);man -t "$@" > "$f" && ( {some-pdf-viewer} "$f" ; rm "$f" ) ... replacing '{some-pdf-viewer}' with whatever PDF viewer works for you. There is probably one that will take the document on stdin, but I am not aware of one. I realize I'm late to the party here, but thought is was worth posting anyway. (edited for typo)

You should be able to avoid using mktemp by: pman='some-pdf-viewer <(man -t "$@")'

Apparently not possible for PDFs, see https://superuser.com/questions/1243405/using-process-substi... . TIL

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

#186

Post by ithkuil »

sedatk wrote: post #181
pimlottc wrote: post #176

Earlier quoted context omitted.

THANK YOU. Showing the usage documentation when the user has explicitly asked for it /is not an error/.

Yes, but many apps show help text when incorrect arguments are provided so, it’s an error in those cases. The dev probably doesn’t want to bother with using different output channels for the same help text.

That a dev of an arbitrary tool may not bother is understandable. However, the dev of the flags parsing library should bother.

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

#187

Post by dxdm »

xeyownt wrote: post #134

> Use a command-line argument parsing library where you can. > ... > Python: Click, Typer What's the problem with using the python standard library argparse? I would frown upon adding a dependency for such a core feature as argument parsing, unless it brings strong benefits. And even then, I'd recommend to use the standard lib and to switch to the other libs only when necessary.

I'd use click over argparse for the same reason I prefer the requests lib over built-ins for standard network communication: it smoothes out the rough edges, cuts down on boilerplate and makes the code easier to read, write and maintain.

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

#188

Post by Aeolun »

AlphaSite wrote: post #148
matt_kantor wrote: post #136

Earlier quoted context omitted.

I'm not who you replied to, but I hardly ever need to use tilde escape sequences to quit ssh. I just terminate the session from inside itself with the `exit` command.

The most common case I’ve hit issues is the remote server is down or blocked but the connection hasn’t yet terminated so exit is no longer possible.

I guess my timeout is really low, so it’ll fail fairly rapidly.

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

#189

Post by pimlottc »

sedatk wrote: post #181
pimlottc wrote: post #176

Earlier quoted context omitted.

THANK YOU. Showing the usage documentation when the user has explicitly asked for it /is not an error/.

Yes, but many apps show help text when incorrect arguments are provided so, it’s an error in those cases. The dev probably doesn’t want to bother with using different output channels for the same help text.

Sure, of course sometimes it should be on stderr. It's a pretty simple fix to have it choose the right channel, though.

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

#190

Post by scbrg »

brabel wrote: post #167
scbrg wrote: post #120

Earlier quoted context omitted.

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…

You should try to configure your terminal to use UTF-8. Symbols are universally used for quickly warning/informing in the real world and if done well, are very intuitive. Ignoring them in the digital world would be going against human UX (but no one ignores them, of course, even very old CLis already used them, but with the widespread use of UTF-8 and Emojis with that, it just became much easier and better).

My terminal has been configured to use UTF-8 for nearly twenty years. Apparently I do not have any font with these glyphs installed though, and I don't think it's reasonable to expect that people do.
Post reply on HN