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  options  required input required input2   options      -a  --argument     Does something     -b required     Does something with  required      -c  --command required     Something else     -d  optlistitem1 optlistitem 2           Something with list   I made that from basically just reading the help text of various tools  but is there a list of guidelines or something  For example  do I use square brackets or parentheses  How to use spacing  What if the argument is a list  Thanks

User · Answer

Microsoft has their own Command Line Standard specification:

This document is focused at developers of command line utilities. Collectively, our goal is to present a consistent, composable command line user experience. Achieving that allows a user to learn a core set of concepts (syntax, naming, behaviors, etc) and then be able to translate that knowledge into working with a large set of commands. Those commands should be able to output standardized streams of data in a standardized format to allow easy composition without the burden of parsing streams of output text. This document is written to be independent of any specific implementation of a shell, set of utilities or command creation technologies; however, Appendix J - Using Windows Powershell to implement the Microsoft Command Line Standard shows how using Windows PowerShell will provide implementation of many of these guidelines for free.

User · Answer

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

User · Answer

yes  you re on the right track   yes  square brackets are the usual indicator for optional items   Typically  as you have sketched out  there is a commandline summary at the top  followed by details  ideally with samples for each option   Your example shows lines in between each option description  but I assume that is an editing issue  and that your real program outputs indented option listings with no blank lines in between  This would be the standard to follow in any case    A newer trend   maybe there is a POSIX specification that addresses this    is the elimination of the man page system for documentation  and including all information that would be in a manpage as part of the program --help output  This extra will include longer descriptions  concepts explained  usage samples  known limitations and bugs   how to report a bug  and possibly a  see also  section for related commands   I hope this helps

User · Answer

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

User · Answer

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  lt argument gt    my program   lt optional-argument gt     my program --another-option  lt with-argument gt    my program  --either-that-option    lt or-this-argument gt     my program  lt repeating-argument gt   lt repeating-argument gt

User · Answer

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

User · Answer

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

User · Answer

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   lt Text inside angle brackets gt   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  lt file gt       Items that can be repeated

[shell] Is there a "standard" format for command line/shell help text?

Examples related to shell

Examples related to command-line

Examples related to command-line-arguments