357

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!

stkent
  • 19,772
  • 14
  • 85
  • 111
Yifan
  • 4,867
  • 5
  • 25
  • 24
  • 8
    I think that GNU has some hints. I would look at what most GNU utilities are doing. – Basile Starynkevitch Mar 15 '12 at 18:15
  • 1
    @DanielPryden I think the answer in that question is a little misleading. It gives links that explain what switches should be accepted and not how the output of `--help` should look. But both questions are a good candidate for a merge. – pmr Mar 15 '12 at 18:31
  • @pmr: I agree -- perhaps a mod can merge the questions for us. – Daniel Pryden Mar 15 '12 at 18:34
  • 2
    I would look at what most GNU utilities are doing, and do it the other way. – Yakov Galka Dec 17 '17 at 19:00

11 Answers11

230

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.

hellow
  • 12,430
  • 7
  • 56
  • 79
davetron5000
  • 24,123
  • 11
  • 70
  • 98
  • 5
    What if I have two forms of a single required arg? E.g. more standard way of saying: `usage: move (+|-)pixels` i.e. when one of `+` *or* `-` is *mandatory*? (I know I can have 2 usage lines but I like the idea of doubling them with each new argument.) Can you think of an example from a standard tool? – Alois Mahdal May 15 '13 at 22:46
  • 6
    @AloisMahdal I usually see `{a|b|c|...}` in the help sections for SysV Init/upstart service scripts, which require a singular argument that is one of `a`, `b`, `c`, etc. For example, `service sddm` without an argument on my system prints out `Usage: /etc/init.d/sddm {start|stop|status|restart|try-restart|force-reload}`. So most people would probably understand `usage: move {+|-}pixels}`, especially if an example is given: `example: move +5` – Braden Best Aug 13 '16 at 22:15
  • @JorgeBucaran they shouldn't be exiting with status 0 should they? I believe exiting with status 2 is the standard for invalid shell commands. – inavda Mar 11 '19 at 22:31
  • Here is a nice summary: http://docopt.org/ – schoetbi Jul 11 '23 at 08:21
140

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>...
Lily Finley
  • 2,847
  • 1
  • 16
  • 11
105

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 for items you must type

    Ex: ls

  • <placeholder for a value>

    Ex: cat <file>, <file> should be replace by the path of the file

  • [optional]

    Ex: ls [-l] can be ls or ls -l

  • {a|b} for mutually exclusive items

    Ex: ip {link|addr} can be ip link or ip addr

  • <file> ... for items can be repeated

    Ex: cat <file> ... can be cat a.txt b.txt c.txt

Steely Wing
  • 16,239
  • 8
  • 58
  • 54
  • There does seem to be a published article by Microsoft @ https://devblogs.microsoft.com/powershell/microsoft-command-line-standard/ which has a little more specificity about the "Microsoft way". Also, it appears that the IBM link referenced is broken. Might not be published anymore or maybe just moved. – Chezzwizz Jun 14 '23 at 17:27
28

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.
Alex
  • 5,759
  • 1
  • 32
  • 47
MotherDawg
  • 669
  • 7
  • 7
  • 4
    It is common that usage in GNU/Linux does not follow exactly this standard. Run e.g. `man aptitude` that outputs this (among other things): `aptitude [...] {add-user-tag | remove-user-tag} ...`. It contains { and } to bind alternative mandatory commands. I think ( and ) could be used for the same like they are used in [docopt](http://docopt.org/). – jarno Mar 01 '16 at 09:59
  • This answer will be a lot less helpful if the provided link goes down. Maybe you could summarize the important parts of the linked document in the answer itself? – domsson Dec 09 '19 at 15:00
  • Although less likely, it is still quite likely that this page might go down one day too :q Just saying. So copying stuff around isn't really the solution for the problem of dead links. We should rather strive for making a less fallible Internet. – SasQ Mar 24 '21 at 22:14
11

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.

Jared Harley
  • 8,219
  • 4
  • 39
  • 48
  • 11
    Microsoft has terrible command line help for most utilities, everything is so awful that they made Powershell to hide the "regular" command line under the carpet. – Camilo Martin Apr 02 '13 at 23:36
  • 40
    I don't think the answer should be downvoted just because it has a reference to Microsoft's standard. "everything is so awful" is a subjective opinion. In a same manner it may be said that UNIX's command line is awful and ugly, but let's keep such opinions away and be professionals. – Dima Apr 18 '16 at 09:13
  • 3
    Agreed, that’s not why this answer should be downvoted. If downvoted, it should be because a) the section of the document that’s been quoted doesn’t answer the question at hand, and b) the document linked to doesn’t seem relevant. The question asks whether there are standards for “help text” with a heavy emphasis on syntax used to communicate command usage synopses. The document does not proffer such a syntax but rather how to build good command line apps in general in the PowerShell ecosystem (e.g. must support `-?`, `-Help`, `-Version`, etc.). IMO Steely Wing’s answer is closer to the mark. – Mark G. Apr 05 '19 at 02:31
  • 1
    But, as steely-wing already mentioned, Microsoft also has this much nicer and simpler document: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/command-line-syntax-key Also, MotherDawg added a link to POSIX, which is the same: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_01 And lily-finley linked the nice http://docopt.org/ So, I would not use this complex Microsoft document – xCovelus Dec 10 '20 at 09:00
11

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.

pmr
  • 58,701
  • 10
  • 113
  • 156
3

There is no standard but http://docopt.org/ has created their version of a specification for help text for command line tools.

apena
  • 2,091
  • 12
  • 19
1

It may be a bit off-topic, but I once wrote two small tools that make creation and maintenance of command line tools help pages more efficient:

  • The MAIN DOCLET that generates an HTML document for the main method of a Java program by processing Javadoc comments in the source code
  • The HTML2TXT tool that formats an HTML document as a plain text (which is what we want our help texts)

I integrate these two tools in the MAVEN build process of my programs so they execute automatically on every build.

For example:

Hope this is useful for others!?

Arno Unkrig
  • 181
  • 2
  • 5
1

I use the CSS formal notation for this.

Component values may be arranged into property values as follows:

  • Several juxtaposed words mean that all of them must occur, in the given order.
  • A bar (|) separates two or more alternatives: exactly one of them must occur.
  • A double bar (||) separates two or more options: one or more of them must occur, in any order.
  • A double ampersand (&&) separates two or more components, all of which must occur, in any order.
  • Brackets ([ ]) are for grouping.

Juxtaposition is stronger than the double ampersand, the double ampersand is stronger than the double bar, and the double bar is stronger than the bar. Thus, the following lines are equivalent:

    a b   |   c ||   d &&   e f
  [ a b ] | [ c || [ d && [ e f ]]]

Every type, keyword, or bracketed group may be followed by one of the following modifiers:

  • An asterisk (*) indicates that the preceding type, word, or group occurs zero or more times.
  • A plus (+) indicates that the preceding type, word, or group occurs one or more times.
  • A question mark (?) indicates that the preceding type, word, or group is optional.
  • A pair of numbers in curly braces ({A,B}) indicates that the preceding type, word, or group occurs at least A and at most B times.

If you need examples, see Formal definition sections on MDN; here is one for font: https://developer.mozilla.org/en-US/docs/Web/CSS/font#formal_syntax.

And here is a simple example from my own Pandoc's cheat sheet:

$ pandoc <input_file>.md --from [markdown|commonmark_x][-smart]? --to html --standalone --table-of-contents? --number-sections? [--css <style_sheet>.css]? --output <output_file>.html
john c. j.
  • 725
  • 5
  • 28
  • 81
1

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.

shellter
  • 36,525
  • 7
  • 83
  • 90
  • 7
    No no no. The command should have a manpage which includes a full detailed reference of use, and `-h|--help` should be just a summarized reference. You may also include more comprehensive documentation (tutorials, etc...) in HTML or info pages. But the manpage should be there! – ninjalj Mar 15 '12 at 18:45
  • I agree with you, @ninjalj, but as I said, "A newer trend", and by that I mean the two systems I use, UWin and MinGW both have gone with embedded documentation. I think embedded doc has it's places, especially for small user-level script, like what this user is proposing. Should he have to learn nroff and .info? But good to keep us honest, thanks for your comments and good luck to all. – shellter Mar 15 '12 at 19:01
  • 1
    Personally, when I type `someCommand --help` at my shell, all I need is a small reminder of the precise order the arguments go in, not a giant swath of text that fills the screen, requiring I pipe it into `less` just to see all of it. The manpage should be where you put the long detailed description, not the help text. – AJMansfield Nov 07 '13 at 16:58
  • according to the maker of docopt in his conference he mentions POSIX has a norm for this. – v.oddou Jun 25 '20 at 08:45
0

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".

rluks
  • 2,762
  • 8
  • 38
  • 56
  • 1
    Regarding `tar`... if someone is going to make a does-everything god-utility like tar, please make the short switches memorable, and include an "example usage" section in the `--help`. 90% of the time I look at tar's instructions it's for extracting a simple `tar.gz`. – Camilo Martin Apr 02 '13 at 23:47
  • 1
    '_There is no real need for "standard help"._' Is there any "real need" for most of the things we use? Or are they just there to make our lives much easier? Having an agreed-upon way to represent options is useful not only for readers, but also e.g. would be useful people building e.g. GUIs that can control arbitrary command-line utilities and want to provide controls for setting their options. There are probably better uses that I didn't consider yet. – underscore_d Nov 03 '17 at 13:39