Command-Line Help for Command-Line Applications

When working with a command-line executable, users need quick access to information about that executable. A user might want to report a bug or consider compatibility issues. In this case, knowing the version number of the executable is critical. Also, users working at the command line need information about the syntax of the executable and its arguments. The most efficient way to provide this information is with command-line help. Command-line help must convey a great deal of information in a small amount of space, and a standard, concise approach for presenting this information is critical.

Version Information

Users access version information for the executable by typing the executable name followed by -version or -v.

For example:

% mytool -version

% mytool 02.03.040-p001

Usage Information

Users access command-line help by typing the command name followed by -help or -h.

Use the following standards to create command-line help for command-line executables.

Include a banner at the top of the help that contains the executable name and version number. The executable name should not be shown with an extension.
Provide a brief usage statement that explains what the executable does. If necessary, add more extensive documentation to the formal documentation set for your tool.
First present the required arguments in alphabetical order. Next present the optional arguments in alphabetical order. If alphabetical ordering is confusing, you can use logical ordering for particular arguments, but keep the rest of the other arguments alphabetical if possible.
If possible, choose argument names that are self-explanatory. Begin argument names with lower case letters. If the argument name is composed of multiple words, capitalize the first letter of each word except the first word.
Use straight brackets to enclose optional arguments.
Provide default values only when necessary.
Use generic terms such as file or number for argument options.
From the longest argument in the list, indent once and provide a short description (follow the guidelines for indention and tabs ). Capitalize the first word of the description. Align the other descriptions with this one.
Do not use positional arguments.
The complete line width for the longest line should be less than 80 characters wide. Shorter is preferable.
Provide options to print command-line help (-h | -help) as well as version information (-v | -version).

The following example shows the correct format for command-line help.

**********************************************************************
mytranslator2oa version 02.03.040-p001
**********************************************************************
Usage:  Translates a file to the destination OpenAccess library.

Syntax: mytranslator2oa         
        -xyz fileList           Quoted, space-separated list of files  
                                to translate
        -lib library            Destination library 
        -topCell name           Top-level cell to translate
        [-cellMap file]         Cell map file
        [-dbuPerUU number]      dbuPerUU value
        [-fontMap file]         Font map file
        [-help | -h]            Print help
        [-hierDepth number]     Hierarchical depth to translate to
        [-ignoreBoxes]          Ignores Stream Box Records
        [-layerMap file]        Layer map file 
        [-logFile file]         Output log file 
        [-noOverwrite]          Existing cells are not overwritten
        [-propMap file]         Property map file
        [-propSeparator char]   Property separator character
        [-refLibList file]      refLibList file
        [-techLib library]      Technology library
        [-techPath path]        Path to the technology library. This arg 
                                is valid only if -techLib is specified.
        [-template file]        Template file
        [-toLower]              Convert cell and instance names to lower
                                case 
        [-toUpper]              Convert cell and instance names to upper 
                                case
        [-view view]            Destination view name. The default name
                                is myview.
        [-version | -v]         Print version information

Return to top of page