Documenting Command-Line Interfaces

A quick guide for creating command-line interface documentation with Docopt.

Docopt is based on established command-line interface (CLI) documentation standards used for decades in help messages and man pages for describing a command-line app’s interface. It both defines the documentation and generates a parser for the code. It includes features such as keyword usage to describe usage patterns. It was introduced in 2012.

Basic Terminology

CLI documentation is made with a description language that uses a specific syntax to create command-line documentation. It includes the following elements and constructs.

Words between less than < and greater than > signs and uppercase words are considered positional arguments.

<argument> ARGUMENT: positional argument

Words starting with one (-) or two (--) dashes are interpreted as short or long options, except if they appear by themselves.

-o --option

Short options can be stacked.

-abc is the same as '-a -b -c'

Options can have arguments.

--input=ARG is euivalent to --input ARG

All other options that don’t follow these patterns are interpreted as subcommands.

Optional Elements

Elements enclosed in square brackets are optional.

Usage: sample_program [command --option <argument>] is the same as 'Usage: sample_program [command] [--opton] []'

Required Elements

Elements are required by default if they aren’t in brackets. You should specify if an element is present or another is required.

This invocation requires either zero or two arguments.

Usage: sample_program[(<one-argument> <another-argument>)]

Use pipe (|) to specify patterns

Use () when one of the mutually exclusive cases is required.

Usage: sample_program (--up | --down | --left | --right)

Use [] to group elements when none is required.

Usage: sample_program [--up | --down | --left | --right]

Specifying several patterns works like pipe (|).

Usage: sample_program run [--fast]
sample_program jump [--high]

is the same as

Usage: sample_program (run [--fast] | jump [--high])

Elements

An ellipsis ... can specify the argument or group of arguments to the left that could be repeated one or more.

Usage: sample_program open <file>...
       sample_program move (<from> <to>)...

There are three ways to specify if zero or more arguments are required.

Usage: sample_program [<file>...]
       sample_program [<file>]...
       sample_program [<file> [<file> ...]]\

Options

An option is a shortcut that avoids listing all options (from a list of options) in a pattern.

This …

Usage: sample_program [options] <path>

--all             List of everything.
--long            Long output.
--human-readable  Display in human-readable format

… Is the same as this

Usage: sample_program [--all --long --human-readable] <path>

[–]
When not used with an option, it separates options and positional arguments. It should be added before positional arguments.

Usage: sample_program [options] [--] <file>...

[-]
It indicates the program should use stdin versus a file when not part of an option. This means input will come from the command line instead of a file.

Option Descriptions

Lists of options are put below the usage patterns. They are optional if there isn’t any ambiguity in usage patterns.

Option descriptions can specify:

  • Whether short and long options are synonymous.
  • If an option has an argument.
  • The default value of an option argument.

Every line that starts with -- or - (not counting spaces) is treated as an option description.

To specify if an option has an argument, put an argument after a space or equal sign (=).

Options:
  --verbose           # GOOD
  -o FILE             # GOOD
Other: --bad          # BAD, line does not start with a dash '-'

Use two spaces to separate options and their descriptions.

-o FILE --output=FILE        # without comma, with'=' sign
-i <file>, --input <file>    # with comma, without '=' sign
--verbose MORE text.        # BAD, will be treated as if verbose
                            option has an argument
-q          Quit.
-o FILE     Output file.
--stdout    Use stdout.

To set a default value for an option with an argument, put it in the option’s description like [default: <the-default-value]

--coefficient=K  The K coefficient [default: 2.95]
--output=FILE  Output file [default: text.txt]
--directory=DIR  Some directory [default: ./]

See Github for Docopts popular repos by programming language.

Scroll to Top