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

#141

Post by nemetroid » Sat, Dec 05, 2020, 5:56 PM UTC

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…

I found it funny how just a few lines down, there's a recommendation to use formatting in your help text, and to "try to do it in a terminal-independent way". This is followed by a Heroku example closely following the manpage style.

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

#142

Post by nemetroid » Sat, Dec 05, 2020, 5:58 PM UTC

_underfl0w_ wrote: post #19

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…

Maybe I'm suffering from similar syndrome, but I'm under 30 in human Earth years. However, I very much agree with you and would take it a step further to say that programmatically opening the browser with the help flag is also very unwelcome (I'm looking at you, git >.> )

Git uses man by default (except perhaps on Windows).

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

#143

Post by tartoran » Sat, Dec 05, 2020, 6:05 PM 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.

I think (correct me if im wrong) tools shells like fish and zsh use the man pages to extract the param suggestions. That saves me so much time

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

#144

Post by woodruffw » Sat, Dec 05, 2020, 6:15 PM UTC

cyberdelica wrote: post #133

woodruffw wrote: post #57

These are some pretty good guidelines! Many thanks to the authors for writing them up. Some nitpicks (what would HN be without nitpicks?): > If your command is expecting to have something piped to it and stdin is an interactive terminal, display help immediately and quit. I disagree with this advice: being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm th…

The man macros for roff/troff/groff are not even particulary complicated. Anyone with half an hour to spend learning them, could write a man page without needing additional tools.

I agree with this (and I maintain a bunch of manual troff, in both senses of the word "manual"), but I also think it isn't the point: the point is that you don't need to learn an additional markup/macro language to produce high-quality manpages.

IME, the tools that are missing nice manpages are less than a decade old and have very good online documentation, particularly in the form of community-assisted ReST or Markdown docs. Most projects would rather just compile those docs into another format than introduce a split maintenance load for manpages.

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

#145

Post by mybrid » Sat, Dec 05, 2020, 6:21 PM UTC

npm is terrible. Why? because the color and formatting outputs all kinds of escape characters. Guess what happens when Jenkins or other build systems try to render spinning ascii characters? What happens if color and spinning punctuation is allowed then developers who use configuration files for things like npm promote them to build with color escape character output enabled. It creates a mess of configuration files keeping separate build and development just for escape character configuration. My advice is no color and no escape characters if your CLI will ever be part of a build chain or is intended to output to logs. All it takes is for one usage to a log that doesn't have '--no-color' and the binary characters will trip up diff and other tools that only work on text.

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

#146

Post by kettro » Sat, Dec 05, 2020, 6:22 PM 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?

Not all terminals support emojis. AFAIR, xterm doesn’t. I was stuck on xterm at my last job (only terminal that really worked on that system). Emojis are for SMS, and that should be it. Use emoticons.

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

#147

Post by kps » Sat, Dec 05, 2020, 7:17 PM UTC

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.

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

#148

Post by AlphaSite » Sat, Dec 05, 2020, 7:30 PM UTC

matt_kantor wrote: post #136

dllthomas wrote: post #98

Earlier quoted context omitted.

I don't understand what you're saying here; could you expand a bit?

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.

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

#149

Post by bewuethr » Sat, Dec 05, 2020, 7:35 PM UTC

tartoran wrote: post #143

throwaway201103 wrote: post #73

Earlier quoted context omitted.

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.

I think (correct me if im wrong) tools shells like fish and zsh use the man pages to extract the param suggestions. That saves me so much time

Bash-completion does something like this for commands with consistent --help output (most Coreutils, bash, awk, grep, sed...) by parsing it in the completion function: https://github.com/scop/bash-completion/blob/29508ce70914f78...

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

#150

Post by matt_kantor » Sat, Dec 05, 2020, 7:41 PM UTC

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.

Yeah, that's the only time I've had to use the escape sequences. However that happens to me only once a year or so (but maybe I don't use ssh as often/in the same ways as others).