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

201–210 of 217 posts

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

#201

Post by alphachloride »

alphachloride wrote: post #200

I think one emoji is one emoji too many. Many terminals do not support them. This also addresses the point of terminal independence you brought up elsewhere. The yubi key example looked like using emojis for the sake of using emojis. Several of them were redundant or only slightly relevant (test tube, hand, key). In all honesty, I just really dislike emojis The guidelines were all helpful otherwise. It shows that I c…

^Like here. I put laugh-crying emojis ironically at the end but they were filtered out. Many terminals wouldn't do me this courtesy of shielding my eyes and instead regurgitate gibberish characters.

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

#203

Post by account42 »

> Don’t bother with man pages.

> If your help text is long, pipe it through a pager.

> Use formatting in your help text.

So reimplement man in a non-standard way? No thanks. Keep --help short and concise and then have a separate man page with all the details. Don't just ignore standards and conventions because not all operating system agree on them.

The languages of the the argument parsing libraries listed (Go, Node, Python, Ruby) is also kinda suspect when many such tools are written in C.

> Use symbols and emoji where it makes things clearer.

Eww. And the example is pretty bad too with a number of meaningless icons.

> By default, don’t output information that’s only understandable by the creators of the software.

Except people with post the default output if they are having problems and having all useful information here saves having to ask for it. Also, don't underestimate your user's abitlity to understand stuff.

> Use a pager (e.g. less) if you are outputting a lot of text.

> A good sensible set of options to use for less

Stop right there. If you going to automatically use a pager, at least use the preferred one the user has specified in their environment. $PAGER is even mentioned later in the environment variable section.

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

#204

Post by account42 »

lokedhs wrote: post #121
antientropic wrote: post #118

Earlier quoted context omitted.

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.

At the very least, use isatty() to check whether the output is actually to a terminal before polluting the log files.

isatty and checking for TERM=dumb are sensible (as well as flags to enable/disable colors). Terminfo however is a meh depencency and since common tools (e.g. git) don't bother either there is no point in anything beyond that.

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

#205

Post by account42 »

kps wrote: post #147
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…

- Don't emit colour unless asked. - Don't assume the user's terminal's background colour. Pragmatically, you can use red; the rest are too light or too dark.

Or just don't use a terminal color scheme where the any foreground color except 30 has bad contrast with color 40 and don't use a default background color that has worse contrast than 40 with all foregreound colors other than 30.

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

#206

Post by account42 »

brabel wrote: post #168
alpaca128 wrote: post #113

Earlier quoted context omitted.

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

Emojis are part of unicode. No need for font awesome to support emojis. Visit https://emojipedia.org and notice how all emojis have their own code point :)

Being part of Unicode does not preclude having to install additional fonts.

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

#207

Post by account42 »

djrhails wrote: post #122
blt wrote: post #95

This is a great resource. I will return to read it closely next time I am designing a CLI. One thing that puzzled me: `git push` is given as an example of the principle "If you change state, tell the user". Its output is: $ git push Enumerating objects: 18, done. Counting objects: 100% (18/18), done. Delta compression using up to 8 threads Compressing objects: 100% (10/10), done. Writing objects: 100% (10/10), 2.09 K…

I think the problem with this approach is when you start to utilise large (normally mono) repos the earlier stages can take significant time. Then you're in a condumdrum of if you make the loading more generic or have an input lag to get to "writing objects".

You could have temporary progress information that (by default) gets overwritten when in an interactive terminal.

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

#208

Post by funcDropShadow »

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.

> "Don’t bother with man pages." Strongly disagree.

Me as well. Though I am not against well linked documentation on the web. But man pages provide several unique advantages.

- Because man pages are installed with the same package the software comes in, their version matches exactly to the version of the installed software.

- Man pages don't require an internet connection or a running server. The internet connection can be a problem in certain kinds of enterprise networks, embedded system or during my commute in the train. The running server costs money who might not be willing to spend it as long as I would like to use the software.

- Linking from the executable to the web is tricky. Does the terminal support clickable links? Which browser should I start? Does it help the user in any way to start a browser on a far away machine that he connected to through ssh, mosh, telnet or morse code over avian carrier?

- It is very easy and safe to open a man page to an unknown command. You can be sure the command is not executed by accident. If I have to type `some-command --help` I am never sure if this is one of those commands that doesn't accept --help and does something stupid instead.

Despite all these advantages of man pages or offline available documentation I also like good online documentation. https://www.postgresql.org/docs/current/ comes to my mind when thinking about excellent software documentation. Granted it is not a one-minute tutorial for the latest newbie. But for someone using that piece of software for years, its value cannot be overstated imho.

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

#209

Post by funcDropShadow »

indymike wrote: post #155
bfirsh wrote: post #152

Earlier quoted context omitted.

The sentiment was meant to be: "Make `command help` as good as a man page. More people will read that." We didn't mean to suggest to use web pages instead. We also didn't mean not to use man pages at all. We just find more people use the built-in help and web pages, so if you have limited time/resources, it's better spent on those things. In retrospect, perhaps it was worded a bit strongly. I am enjoying the debate,…

Having good `command help` is super important. Agree with the assertion that in-built help is the first and most important. There have been so many tries to make something better than man pages, and all of them tend to fall down because the solution is usually super complex. Usually, you are dealing with html or some archeo-crontastic typesetting format (which honestly, gets you man + hyperlinks and some better forma…

Relying on `command help` with an unknown command can be dangerous.

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

#210

Post by stult »

bfirsh wrote: post #152
kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

The sentiment was meant to be: "Make `command help` as good as a man page. More people will read that." We didn't mean to suggest to use web pages instead. We also didn't mean not to use man pages at all. We just find more people use the built-in help and web pages, so if you have limited time/resources, it's better spent on those things. In retrospect, perhaps it was worded a bit strongly. I am enjoying the debate,…

Regarding web pages, some people work in highly controlled environments where you only have access to the man pages because you are working on a limited intranet designed for sensitive data, e.g. defense contractors or people working with sensitive health data. So having colocated resources can be extremely valuable for a small subset of users and shouldn't be completely discouraged. Although I agree with your assessment that command help and web pages are where the priority should be, since that meets the needs and expectations of a much larger proportion of CLI users.
Post reply on HN