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). The configuration data and its persistence are owned by DefaultConfigurationService, which is passed directly to the config group commands. Only a view exposing the config file location is registered under CONFIGURATION_SERVICE_ID.

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 file (JSON by default, see ConfigFormat) 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 (or <group name>:<member name> for a member of a GroupCommand) and the contained values are treated as command Values. As an example:

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

The syntax of the file is set by the configFormat constructor argument: JSON (the default), or YAML or TOML from the yaml and toml entry points of this package. The format is never inferred from the file name or extension and existing files are not migrated between formats. For YAML and TOML, comments and layout in the existing file are preserved when it is written back.

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

NOTE: Secrets in default arguments are referenced in the config file or an environment variable using the sentinel format __SECRET__:<bun_secret_name> and resolved from the OS secret store before being returned as default argument values. A command's defaults may only reference secrets stored for that command via config set (named defaults_Z<command>_Z<option path>, each part escaped). 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 prefixed with the CLIConfig.name, the GroupCommand.name (if the command is a group member) 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, group: group1, member command: member1, simple root argument: arg1 => environment variable: MYCLI_GROUP1_MEMBER1_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.