Should the command line "usage" be printed on stdout or stderr?

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?

Gaddi

Answer 1

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.

Tightlipped

I agree. You should also consider exit code - if the program is called with wrong arguments, it should return 1, if it is called with --help or similar, it should return with 0. – Folkways

Thanks for the precision about stdout when explicitly requested (such as --help). That made the accepted answer. – Opportina

Thank you Alex for the precision about 0 and 1. That would have been another question without your answer here ;) – Opportina

@Alex: Totally agree, though unfortunately there's no universally accepted standard on return values. Zero is a good success value though in my opinion. – Tightlipped

@OregonGhost: There is an accepted standard. Programs always return zero on success and !0 on error (return values for errors are not defined though, they just have to be != 0). – Lobar

@dbemerlin: That is theoretical. I have a lot of command line tools here that return some value other than zero for success. One of them returns 42, but there are others that return a lot of things. This means you simply can't count on a command line program returning zero for success, which (in my opinion) means there is no universally accepted standard. It would be great if it was that easy, but it isn't. – Tightlipped

Answer 2

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.

Dagenham

GNU Coding Standards says it goes to standard output. I wonder if popt has a configuration option to make it compliant. – Oldtime

Answer 3

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.

Amenra

Answer 4

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.

Evanevander

Answer 5

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.

Lobar

I think you're right about parameter errors, but why does "usage" need to be in the cron logs? – Amiraamis

Answer 6

if --help then stdout, else stderr. Here's the JCommander code for Java users:

MyOptions myOptions = new MyOptions();
JCommander jCommander = new JCommander(myOptions);

try {
    jCommander.parse(args);
} catch (ParameterException exp) {
    /* print the exp here if you want */
    StringBuilder sb = new StringBuilder();
    jCommander.usage(sb);
    System.err.println(sb.toString());
    System.exit(1);
}

if(myOptions.isHelp()) {
    jCommander.usage();
    System.exit(0);
}

Wire

Answer 7

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.

Floating

Answer 8

Should the command line “usage” be printed on stdout or stderr?

I think it depends on the organization's coding standards. Outside an organization, its probably one of those topics that are endlessly debated, like which is the best operating system, which is the best editor, which is the right religion, ...

Browsing Java Code Conventions (SEPT 1997), Java does not specify it. There is no answer, and it will be endlessly debated.

According to GNU's coding standards, it should be printed on standard output:

4.7.2 --help

The standard --help option should output brief documentation for how to invoke the program, on standard output, then exit successfully. Other options and arguments should be ignored once this is seen, and the program should not perform its normal function.

Near the end of the ‘--help’ option’s output, please place lines giving the email address for bug reports, the package’s home page (normally ‘http://www.gnu.org/software/pkg’, and the general page for help using GNU programs. The format should be like this:

Report bugs to: mailing-address
pkg home page: <http://www.gnu.org/software/pkg/>
General help using GNU software: <http://www.gnu.org/gethelp/>

It is ok to mention other appropriate mailing lists and web pages.

---

Here's the related topic of "version". Its also from the GNU coding guide, and it also writes to standard output:

4.7.1 --version

The standard --version option should direct the program to print information about its name, version, origin and legal status, all on standard output, and then exit successfully. Other options and arguments should be ignored once this is seen, and the program should not perform its normal function.

The first line is meant to be easy for a program to parse; the version number proper starts after the last space. In addition, it contains the canonical name for this program, in this format:

GNU Emacs 19.30

The program’s name should be a constant string; don’t compute it from argv[0]. The idea is to state the standard or canonical name for the program, not its file name. There are other ways to find out the precise file name where a command is found in PATH.

If the program is a subsidiary part of a larger package, mention the package name in parentheses, like this:

emacsserver (GNU Emacs) 19.30

If the package has a version number which is different from this program’s version number, you can mention the package version number just before the close-parenthesis.

If you need to mention the version numbers of libraries which are distributed separately from the package which contains this program, you can do so by printing an additional line of version info for each library you want to mention. Use the same format for these lines as for the first line.

Please do not mention all of the libraries that the program uses “just for completeness”—that would produce a lot of unhelpful clutter. Please mention library version numbers only if you find in practice that they are very important to you in debugging.

The following line, after the version number line or lines, should be a copyright notice. If more than one copyright notice is called for, put each on a separate line.

Next should follow a line stating the license, preferably using one of abbreviations below, and a brief statement that the program is free software, and that users are free to copy and change it. Also mention that there is no warranty, to the extent permitted by law. See recommended wording below.

It is ok to finish the output with a list of the major authors of the program, as a way of giving credit.

Here’s an example of output that follows these rules:

GNU hello 2.3
Copyright (C) 2007 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

...

Oldtime