Should the command line “usage” be printed on stdo

Question

When printing the "usage" of an application, should it be done on stdout or on stderr?

Depending on the application I've seen several cases, but there doesn't seem to be one rule. Maybe I'm mistaken and there is one good practice. In that case, what is it?

Answer 1

I'd use STDERR since simply putting it to STDOUT might cause problems with piped output and it will appear in the logs for cronjobs so you notice the mistake easier.

Answer 2

This can only be opinion, but I think writing to stderr is the best thing to do. That way the usage message appears if the user makes a mistake even if the normal output has been re-directed.

Answer 3

According to me, the criteria is how emergence is the information. If it needs immediate reaction or attention, I put it into stderr (cause it's unbuffered). If it is somehow informative and do not regard any errors it is for stdout.

Answer 4

I agree that explicitly requested "usage" (through a -h, -? or --help option) should go to stdout while "usage" that is printed in response to incorrect syntax or other errors should go to stderr.

However, note that the increasingly popular popt library (which handles command line parsing; its name stands for "parse options") includes a facility for automatically generated help and that it always sends that to stderr. I quote the popt man page:

When --usage or --help are passed to programs which use popt's automatic help, popt displays the appropriate message on stderr as soon as it finds the option, and exits the program with a return code of 0.

I believe this to be a popt bug, but the problem is that POSIX (or ISO C, to which it defers) never defined what was meant by "diagnostic output". Just read 'man stderr' or POSIX.1-2008.

Answer 5

I'm always bothered by programs that have a lot of options that don't fit on screen, but when run as program --help | less, I can't see anything since the help was actually sent to stderr.

I like the idea of explicitly requested usage (i.e. --help option) should send output to stdout. In case of invalid options I think it's not necessary to display detailed usage information. There definitely should be an error message like Invalid option "--some-option". Run "program --help" for usage information. sent to stderr. If the program decides to output usage information by default on invalid options or when invoked without options, I think there should be a short error message complaining about invalid usage, but the help itself may go to stdout.

Answer 6

Never thought about it, but why not write the usage instructions to stderr if the program was called with no or wrong arguments, and write it to stdout when called with a --help (or similar) argument? This way, if the usage is shown because of an error, it goes to stderr, and if it's not an error because the user requested it, it goes to stdout. Seems logical, somehow.