CommandLineSource

The CommandLineSource is by necessity the most complex of the default sources, as it needs to present a friendly face to users.

The behavior of CommandLineSource is primarily driven by field options; see the field option documentation for details, but the most relevant attributes that control the command line are: flagHint, advanced, hidden, allowEmpty, and description.

Configurable fields are mapped to "long" command-line options by converting the field path to kebab-case.

If the first element of the field path matches the appName property in the context, this is trimmed, making the child schema corresponding to the app have the simplest options.

Flags are then generated, first from any field that defines a flagHint, and then from any "top-level" long option (e.g. without a hyphen) that isn't marked advanced or hidden. If there is a collision, it tries to create a capitalized flag.

Finally, any multi-word long option has a short alias generated from the initial letters, if available.

Flags and aliases are allocated in definition order. Use flagHint to prioritize or set a flag for a nested child field.

The overall behavior is best demonstrated with an example; here is the output of running the basics example and passing --help advanced on the command line:

  --codes (-c) <value...>                                    - (required)
  --verbose [true|false]                                     - (advanced)

  --server-host (--sh) <string-value>                        - (default: localhost)
  --server-port (--sp) <number>                              - (default: 80)
  --server-protocol <string-value>                           - (advanced)

Observe that --debug is not shown at all (it has the hidden attribute) but it does exist. The field paths corresponding to the basics child have been trimmed, as they match the appName. Because --codes is a top-level option that isn't advanced, it got assigned -c as a flag. Finally, --server-protocol didn't get an alias because it is advanced, but it also was defined after --server-port so it would have lost out anyway as --sp was taken.

By default, CommandLineSource will parse a argv property in the context (this can be changed by setting the contextFieldName option in the constructor). If no context field is present, it uses process.argv.

Constructor

new CommandLineSource(options)

Param	Type	Description
[`options`]	`object`	Optional settings (described below)
[`options.sequence`]	`number`	Defaults to ConfigurationSource.DefaultSequence.ARGUMENTS (500)
[`options.contextFieldName`]	`string`	Name of field to parse from context (default: "argv")
[`options.helpEnabled`]	`boolean`	Enable/disable the help options. Defaults to true.
[`options.helpOption`]	`string`	Name of the option that shows help (--help)
[`options.helpFlag`]	`string`	Flag name for help (-h)
[`options.helpDescription`]	`string`	Override description of the help option
[`options.helpValueDescription`]	`string`	Override description of the help option value

Constructor​

Constructor