Class ConfigurationServiceProvider

Provides:

• Configuration of default command arguments using a configuration file and/or environment variables.
• A generic key-value store for commands and services (KeyValueService).

Default Command Arguments

Configuration of default ArgumentValues 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 ArgumentValues 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 ArgumentValues. 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 "Generic Key-Value Service" below.

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.

Generic Key-Value Service

The same configuration file above is used to provide storage for the provided KeyValueService. The values are stored under a top level key-values property. These are expected to not be modified by the user of the CLI.

The second and third level of properties is used to scope the key-values to specific command names (via Command.name values) and specific service IDs (via ServiceProvider.serviceId values). Both keys and values are string based.

Values may be stored as OS-native secrets via KeyValueService.setKey with isSecret=true. When a value is stored as a secret, a sentinel value of the format __SECRET__:<bun_secret_name> is stored in the config file instead of the actual value. The actual value is stored in the OS credential store via Bun.secrets. The sentinel prefix __SECRET__: is reserved and must not be used for regular key-value data.

Secret support requires secretServiceEnabled=true in the constructor (which also requires configEnabled=true).

As an example:

{
   "defaults": {
       ...
   },
   "key-values": {
       "commands": {
           "command1": {
              "foo1": "bar1",
              "foo2": "__SECRET__:command_command1_foo2"
           },
           "command2": {
               "foo1": "bar3"
           }
       },
       "services": {
           "service-id-1": {
               "foo1": "bar"
           }
       }
   }
}
Copy