Tell HN: Please don't print –-help to stderr in your CLI tools

(Of course, an alternative argument is that commands should fail silently but emit a nonzero return value.)

When invoked directly, as with '-h' '--help', etc., help output should write to stdout, and not stderr.

StackOverflow has tackled this question, 2nd response follows the course I suggest:

<https://stackoverflow.com/questions/1068020/app-help-should-...>

And in this case, the first response:

<https://stackoverflow.com/questions/2199624/should-the-comma...>

I'm looking for any specific guidance from, e.g., GNU but am not finding any.

    foo --help 2>&1 | less

The output of --help is not an error message, it's the legitimate and expected output of the program when invoked with that argument.

Many tools, for consistency or for laziness always print usage to stderr. But it is better than always printing it to stdout. Errors should never go to stdout, and paging stderr can easily be done with 2>&1.

Edit: and maybe, if your --help output is several pages long, consider leaving out the details to a manpage.

Windows Powershell gives you the detail of git push in scary red text.

https://stackoverflow.com/questions/12751261/powershell-disp...

You would use stderr for status messages, error messages, and other stuff that is not the primary output of the program. (In some cases, this might include help text; like another comment says, if you specified wrong arguments (not --help) then a short description might be a part of the error message.)

One program that does write error messages to stdout and that annoys me significantly is Ghostscript. (Although you can tell it to write it to stderr, doing that causes all output to be written to stderr; I want output from "print", "==", etc to be written to stdout.)

However, if you used the tool incorrectly (passed the wrong args) and you expected the usage information to go to stdout rather than stderr, I would disagree vehemently. stdout is (generally) for parseable information, whereas stderr is kind of a garbage bin of everything else.

For example, many programs will print usage/help when used incorrectly. Imagine you upgrade the "read_reactor" tool, and your usage in your "control_reactor" becomes invalid - suddenly you're piping help message data to the control rods. By sending it to stderr instead, no bogus data would be piped and, as a bonus, you would see the help message after invoking your script because (as you have experienced) stderr is not piped by default.

If you want to send it to less: read_reactor -h 2>&1 | less

Not quite the same, but I really dislike programs which log status updates and more fundamental output to the same place.

IIRC, ffmpeg is like this with everything going to stderr, making metadata parsing more difficult than it needs to be.

Standard output is for program output. Standard error is something of an unfortunate name since it's actually a side channel for all non-output messages meant for the user to read.

So what's "output" anyway? Whatever the user asked the program to compute. If you pass a --help option, the help message is clearly the program's output because it's what the user asked for. If you use it incorrectly and the program prints usage information, the help message should go to standard error while the output is empty because the operation failed.

  static void usage(const char *arg0, FILE *fp);

  case 'h':
    usage(argv[0], stdout);
    return 0;
  default:
    usage(argv[0], stderr);
    return EXIT_FAILURE;
  }

    $ foo -h

when I rerun with --help, it prints a worse than useless usage string and says "for more help, type --help-advanced"

https://github.com/sharkdp/bat#highlighting---help-messages

  # in your .bashrc/.zshrc/*rc
  alias bathelp='bat --plain --language=help'
  help() {
      "$@" --help 2>&1 | bathelp
  }

--help, when used correctly, is almost always interactive, where stdout/stderr and exit status don't matter at all. The few noninteractive uses like help2man or zsh auto parsing can trivially handle a redirect. Sure, a noob piping --help to less may be confused for a first time, that's rare and it's a good chance for them to learn about streams and redirection.

That leaves accidental noninteractive usage. Sooner or later someone will call your program with dynamic arguments from another program, and if your command accepts filenames/IDs there's always a chance to encounter one that starts with '-' and contains an 'h' (a practical example: YouTube video IDs). It's very easy to forget to add -- before the unsafe argument(s), so that it's accidentally interpreted as flags. Nonempty stdout, empty stderr and zero exit status makes it way too easy to accidentally accept the output as valid, only to discover much later.

This is not a theoretical concern, I've made this mistake myself and had it masked by -h behavior. A noob only need to learn redirection once, in a totally harmless setting. Meanwhile, even the most seasoned expert could forget -- in a posix_spawn.

At the end of the day, this is not a big deal, but as I said, if you have to make a conscious choice, make the one that makes accidental mistakes more obvious, because humans do make mistakes. This principle applies everywhere.

  use Getopt::Long;
  use Pod::Usage;
  =pod
  ... your scripts documentation here...
  =cut
  GetOptions(
    'help' => sub{ pod2usage(-exitval=>0, -verbose=>99); },
  ) or pod2usage(-exitval=>2, -verbose=>99);
  =pod
  ... continuing here...
  =cut

The GNU Project has published tools of varying quality, based on who was around to write the tool, debug it, give feedback, etc. It is not the exemplar of high quality software. (But it's far from crap.) The important bit about GNU (and any other software) is that it was written to adhere to their uses. Other people have different requirements. Telling people to "write your software like GNU writes their software" is to misunderstand personal agency and one of the major points of open source software.

Your comments sound like you're saying "Software freedom means you're free to write software the way I want you to write software."

No thank you.

Saves a few characters compared to 2>&1

  asdf --help 2>&1 | less