Is there a “standard” format for command line/shell help text?

Question

If not, is there a de facto standard? Basically I\'m writing a command line help text like so:

usage: app_name [opti         


        

Answer 1

The GNU Coding Standard is a good reference for things like this. This section deals with the output of --help. In this case it is not very specific. You probably can't go wrong with printing a table showing the short and long options and a succinct description. Try to get the spacing between all arguments right for readability. You probably want to provide a man page (and possibly an info manual) for your tool to provide a more elaborate explanation.

Answer 2

Typically, your help output should include:

• Description of what the app does
• Usage syntax, which:
  • Uses [options] to indicate where the options go
  • arg_name for a required, singular arg
  • [arg_name] for an optional, singular arg
  • arg_name... for a required arg of which there can be many (this is rare)
  • [arg_name...] for an arg for which any number can be supplied
  • note that arg_name should be a descriptive, short name, in lower, snake case
• A nicely-formatted list of options, each:
  • having a short description
  • showing the default value, if there is one
  • showing the possible values, if that applies
  • Note that if an option can accept a short form (e.g. -l) or a long form (e.g. --list), include them together on the same line, as their descriptions will be the same
• Brief indicator of the location of config files or environment variables that might be the source of command line arguments, e.g. GREP_OPTS
• If there is a man page, indicate as such, otherwise, a brief indicator of where more detailed help can be found

Note further that it's good form to accept both -h and --help to trigger this message and that you should show this message if the user messes up the command-line syntax, e.g. omits a required argument.

Answer 3

I would follow official projects like tar as an example. In my opinion help msg. needs to be simple and descriptive as possible. Examples of use are good too. There is no real need for "standard help".

Answer 4

Take a look at docopt. It is a formal standard for documenting (and automatically parsing) command line arguments.

For example...

Usage:
  my_program command --option <argument>
  my_program [<optional-argument>]
  my_program --another-option=<with-argument>
  my_program (--either-that-option | <or-this-argument>)
  my_program <repeating-argument> <repeating-argument>...

Answer 5

I think there is no standard syntax for command line usage, but most use this convention:

Microsoft Command-Line Syntax, IBM has similar Command-Line Syntax

---

• Text without brackets or braces

  Items you must type as shown
  
  

• <Text inside angle brackets>

  Placeholder for which you must supply a value
  
  

• [Text inside square brackets]

  Optional items
  
  

• {Text inside braces}

  Set of required items; choose one
  
  

• Vertical bar {a|b}

  Separator for mutually exclusive items; choose one
  
  

• Ellipsis <file> …

  Items that can be repeated
  
  

Answer 6

We are running Linux, a mostly POSIX-compliant OS. POSIX standards it should be: Utility Argument Syntax.

• An option is a hyphen followed by a single alphanumeric character, like this: -o.
• An option may require an argument (which must appear immediately after the option); for example, -o argument or -oargument.
• Options that do not require arguments can be grouped after a hyphen, so, for example, -lst is equivalent to -t -l -s.
• Options can appear in any order; thus -lst is equivalent to -tls.
• Options can appear multiple times.
• Options precede other nonoption arguments: -lst nonoption.
• The -- argument terminates options.
• The - option is typically used to represent one of the standard input streams.