Environment Variables

Overview

Imperative allows CLI users to specify the following using operating system environment variables:

• Logging Level
• home directory
• Command options

Naming Conventions

Imperative automatically generates environment variables using your Imperative CLI name as the prefix (for example, samp). The CLI name can be specified on your Imperative configuration name property. If name is absent from the configuration, it will be extracted from your package.json name property.

Imperative generates environment variables using the following format:
<prefix>_<ENV_VAR_SUFFIX>

You can override the default prefix on the Imperative configuration document envVarPrefix property.

Note: When you allow Imperative to default to using your CLI name as the prefix, ensure that you use characters in the name of your CLI that are valid characters for environment variables. This stipulation also applies to using the prefix property. No transformation/validation will be performed.

List of Generated Environment Variables

Env Variable	Description	Values	Default
<prefix>_APP_LOG_LEVEL	Application logger level (for example, your CLI built on Imperative)	Log4JS log levels (OFF, TRACE, DEBUG, INFO, WARN, ERROR, FATAL)	DEBUG
<prefix>_IMPERATIVE_LOG_LEVEL	Imperative core logger level (i.e. internal imperative)	Log4JS log levels (OFF, TRACE, DEBUG, INFO, WARN, ERROR, FATAL)	DEBUG
<prefix>_CLI_HOME	The directory to place the Imperative CLI home directory. The home directory is always prefixed with "." and contains profiles, logs, settings, and more.	A valid file system path.	require('os').homedir()
<prefix>_OPT_<option name>	Imperative allows (almost) any command line option to be specified via environment variable.	Dictated by the command definition.	Dictated by the command definition.

Note: Setting the log level to TRACE or ALL may result in "sensitive" data being logged. For example, command line arguments will be logged when TRACE is set.

Specifying Command Options with Environment Variables

Imperative allows CLI users to specify (almost) any command line option via environment variable. This can be very useful in scripting environments.

Assume we have the following Imperative configuration document:

"imperative": {
    "name": "hello",
    "productDisplayName": "Hello World",
    "definitions": [{
        "name": "world",
        "description": "Say Hello World!",
        "type": "command",
        "handler": "/path/to/handler",
        "options": [{
            "name": "additional-greeting",
            "description": "An additional greeting!",
            "type": "string",
            "required": true
        }]
    }],
    "rootCommandDescription": "Welcome to the Hello World CLI!",
    "envVariablePrefix": "HELLO"
}

The user can specify a value for --additional-greeting using an environment variable:

export HELLO_OPT_ADDITIONAL_GREETING="Hello Universe!"

Now the user can issue the command without specifying the option and the value will be extracted from the environment variable:

hello world

Note: --help cannot be specified via environment variable and Imperative does not currently allow usage of aliases in environment variables.