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 driven by schema properties and options and customized with metadata:

Metadata Name	Description
`advanced`	hides option from help unless `--help advanced` is specified
`description`	describe purpose of the property for help
`flagHint`	request a specific single-character flag
`general`	gathers arguments provided without an option/flag (e.g filename lists)
`hidden`	hides option from help, but it exists
`internal`	do not generate a command line option at all
`valueDescription`	describe legal values for the property

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

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

Flags are then generated, first from any property that defines flagHint metadata, 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 metadata to prioritize or set a flag for a nested property.

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

Usage: basics [options]
  --codes (-c) <alphanum...>     - (required)
  --config (-C) [path|-]         - load configuration from file (or - for stdin)
  --debug (-D) [true|false]      - (default:false)
  --help (-h) [advanced]         - display help information
  --verbose (-v) [true|false]
  --server-host (--sh) [string]  - (default:127.0.0.1)
  --server-port (--sp) [number]  - (default:80)
  --server-protocol [http|https] - (default:http)

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

Commands

Creating a CLI with commands and subcommands is documented separately in the Commands Guide.

From that section, observe how the selector, selection, and general drive the parsing syntax:

Usage: spm [options] [install|run|test [options]]
                                      
  --config (-C) [path|-]               - load configuration from file (or - for stdin)
  --help (-h) [advanced]               - display help information
                                      
  install [options] <package-name...>  - install specified packages
    --global (-g) [true|false]        
    --save (-s) [true|false]          
    --save-dev (-S) [true|false]      
                                      
  test [options]                      
    --ignore-scripts (-i) [true|false]
                                      
  run [options] script-name           
    --if-present (-i) [true|false]    
    --workspace (-w) [string] 

Help, Config, and Dump Options

The Configurator class automatically adds special schemas for help, config file loading, and dump output unless disabled. These schemas have special configuratorSchema metadata that CommandLineSource recognizes:

Help schema (configuratorSchema: 'help') - Enables --help and --help advanced options
Config schema (configuratorSchema: 'config') - Enables --config <path> for loading config files
Dump schema (configuratorSchema: 'dump') - Enables --dump <path> for outputting configuration

These are automatically created by Configurator (see Configurator.createHelpSchema(), etc.) but you can provide your own schemas with this metadata to customize behavior.

API

See the CommandLineSource API for more info.

Commands​

Help, Config, and Dump Options​

API​

Commands

Help, Config, and Dump Options

API