Class ConfigurationServiceProvider

Provides configuration of default command arguments using a configuration file and/or environment variables.

The same configuration file also backs the raw, per-scope key-value data consumed by KeyValueServiceProvider (which holds a direct reference to this provider - see getKeyValueData and flushIfDirty - rather than looking this provider up via Context, since only configLocation/setConfigLocation are safe to expose generally; getConfigString is wired directly to DumpConfigCommand for the same reason - a full config dump would leak every other command's/service's key-value data if it were reachable through a general lookup).

Default Command Arguments

Configuration of default Values for Command instances is supported if they have defined Command.enableConfiguration as true.

Two sources of configuration are supported and both are expected to be manually managed by the user of the CLI.

Configuration File

A JSON file where the structure matches Values and the defaults are stored under a top level defaults property. The second level of properties is used to refer to Command.name and the contained values are treated as command Values. As an example:

{
    "defaults": {
        "subCommand1": {
            "arg1": [
                1,
                2
            ],
            "arg2": {
                "arg3": "foo"
            }
        },
        "command2": {
            "arg4": true
        },
        "globalCommand": "globalArgumentValue"
    },
    "key-values": {
        ...
    }
}
Copy

The default location of the configuration file is $HOME/.<application_name>.json. If $HOME is not defined no default configuration will be used. The location of the configuration file can be modified via the ConfigCommand.

NOTE: You may store default arguments for secrets by manually configuring secrets in your OS credential store and referencing them in the config file using the sentinel format __SECRET__:<bun_secret_name>. These values will be resolved from the OS secret store before being returned as default argument values. See KeyValueServiceProvider for the generic key-value store which uses the same secret sentinel mechanism.

Environment Variables

Values are parsed using a key path defined by custom Argument.configurationKey values or using the default naming scheme defined within Argument.configurationKey.

NOTE: Any values set by environment variables will override those sourced from the configuration file.

The argument key path is derived for an argument (or nested argument) as follows:

Argument configuration keys are concatenated with a _ separator. Any arguments which support array values must by suffixed with _ and an explicit array index. If the root argument in the path does not use a custom Argument.configurationKey then the key path is additionally suffixed with the CLIConfig.name and the Command.name with _ separators. This is best explained with examples...

No custom configuration key examples:

• executable: MyCLI, command: globalCommand1, global command argument => environment variable: MYCLI_GLOBALCOMMAND1
• executable: MyCLI, command: command1, simple root argument: arg1 => environment variable: MYCLI_COMMAND1_ARG1
• executable: MyCLI, command: command1, array root argument, 1st element: arg2[0] => environment variable: MYCLI_COMMAND1_ARG2_0
• executable: MyCLI, command: command1, argument is a digit so it is by default suffixed with _: 3 => environment variable: MYCLI_COMMAND1__3
• executable: MyCLI, command: command1, nested sub-argument: arg1.arg2 => environment variable: MYCLI_COMMAND1_ARG1_ARG2
• executable: MyCLI, command: command1, nested sub-argument with both levels being arrays and referring to the 2nd element of each: arg1[1].arg2[1] => environment variable: MYCLI_COMMAND1_ARG1_1_ARG2_2

Custom configuration key at the root level (and therefore not prefixed with CLI and command names) examples:

• executable: MyCLI, command: globalCommand1, global command argument, global command argument configuration key: FOO=> environment variable:FOO`
• executable: MyCLI, command: command1, simple root argument: arg1, arg1 configuration key: FOO => environment variable: FOO
• executable: MyCLI, command: command1, array root argument, 1st element: arg2[0], arg1 configuration key: BAR => environment variable: BAR_0

Custom configuration key not at the root level (and therefore prefixed with CLI and command names) examples:

• executable: MyCLI, command: command1, nested sub-argument: arg1.arg2, arg2 configuration key: FOO => environment variable: MYCLI_COMMAND1_ARG1_FOO
• executable: MyCLI, command: command1, nested sub-argument with both levels being arrays and referring to the 2nd element of each: arg1[1].arg2[1], arg2 configuration key: BAR => environment variable: MYCLI_COMMAND1_ARG1_1_BAR_2

NOTE: Any default values from the above configuration sources will be overridden by any arguments provided on the command line.