cmd-line-args

This is a wrapper for the Node.js packages command-line-args and command-line-usage that adds support for positional arguments.

Additionally, the wrapper automatically uses "command-line-usage" to provide an usage guide from the same input.

Positional arguments

In place of the defaultOption argument, one or more of the arguments can be marked with positional: true. The relative order of positional arguments in the option definitions array is significant.

The last positional argument can have multiple: true, in which case the given values are returned as an array.

Internally, the wrapper combines the positional arguments into a single defaultOption argument, and after parsing again splits them back into multiple arguments according to the option definitions array.

Note: The input to the wrapper must not include a defaultOption argument. Use positional instead.

Mandatory arguments

Arguments can be marked mandatory with mandatory: true. If a mandatory argument is not given, usage help is shown and the process exits.

For positional arguments, mandatory arguments must be listed before optional arguments. This is because the relative order of positional arguments is significant.

Usage help

The first two arguments to the wrapper are the name and description of the command. Additionally, each argument can be provided with a description property that contains a human-readable description.

By default, the wrapper injects a --help or -h option that can be used to show usage help. If you need to use -h for some other purpose, pass { nohelp: true } as the last argument to the wrapper.

Example

In the following example there are two positional arguments, the latter of which (file) can be speficied multiple times. In addition, there are three optional named arguments.

cmdLineArgs(
   'grep',
   'Search for patterns in input',
   [
      { name: 'pattern', positional: true, mandatory: true, description: 'Regular expression' },
      { name: 'file', positional: true, multiple: true, description: 'One or more filenames' },
      { name: 'invert', alias: 'v', type: Boolean, description: 'Print non-matching lines' },
      { name: 'before', alias: 'B', type: Number, description: 'Print lines before context' },
      { name: 'after', alias: 'A', type: Number, description: 'Print lines after context' }
   ]
);

If the program is run without any arguments, the program automatically exits and the following output is printed to guide the user:

Missing positional argument: pattern

Run "grep --help" for usage help

If the user runs the program with --help the full usage help is shown. The format of this usage help is fixed, but should follow common conventions.

grep

  Search for patterns in input

Synopsis

  $ grep pattern [file...]

Positional arguments

  pattern   Regular expression
  file      One or more filenames

Optional arguments

  -v, --invert          Print non-matching lines
  -B, --before number   Print lines before context
  -A, --after number    Print lines after context
  -h, --help            Show this help