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 schema metadata; see the Schema API documentation for details, but the most relevant metadata that controls the command line are: _flagHint, _advanced, _hidden, _allowEmpty, _description, and _valueDescription.

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 advanced on the command line:

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

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

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.

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.

Constructor

new CommandLineSource(options)

Param	Type	Description
[options]	object	Optional settings (described below)
[options.sequence]	number	Priority number. Defaults to ConfigurationSource.DefaultSequence.ARGUMENTS (600)
[options.contextName]	string	Name of context field to parse (default: "argv")

Examples

Basic Usage

import { CommandLineSource } from '@versionzero/configurator/sources';

// Use default context name ('argv')
const source = new CommandLineSource();

// Or specify custom context name
const source = new CommandLineSource({ contextName: 'args' });

With Custom Priority

// Place command line parsing after custom source
const source = new CommandLineSource({ sequence: 700 });

Complete Example

import { Schema, Configurator } from '@versionzero/configurator';

const schema = new Schema('object')
  .property('verbose', new Schema('boolean')
    .meta('_flagHint', 'v')
    .meta('_description', 'Enable verbose output')
  )
  .property('output', new Schema('string')
    .meta('_description', 'Output file path')
    .default('output.txt')
  );

// CommandLineSource is included in default sources
const config = await Configurator.load(schema);

// Or use it explicitly
const config = await Configurator.load(schema, {
  sources: [new CommandLineSource()]
});