# Environment variables

[&#x2190; Authentication and authorization](authentication-authorization.md)

The `dsh` tool can be run entirely from the command line and
all configurations and parameters can be specified via command line arguments.
However, especially when using `dsh` interactively,
it is much more convenient to make some settings persistent via environment variables.

The `dsh` tool can print a list of all used environment variables via the command:

```shell
> dsh --env-vars
```

A detailed explanation of an environment variable can be printed via the commands:

```shell
> dsh --env-var DSH_CLI_DRY_RUN  # Explains environment variable "DSH_CLI_DRY_RUN"
> dsh --env-var dry              # Explaines all variables that contain "dry" (case insensitive)
```

Environment variables can be set in three ways:

#### Shell command or shell script

Typically, environment variables are set using shell commands or shell scripts. This makes them
available for the lifetime of the shell, or until they are explicitly unset.

```
> export DSH_CLI_LOG_LEVEL=debug
```

#### Command line argument

Environment variables can also be specified using command line arguments. This way they have to
be specified with every invocation. Note that this is similar to using the command line
options directly.

```
> dsh platforms --environment-variable DSH_CLI_LOG_LEVEL=debug
> dsh platforms -e DSH_CLI_LOG_LEVEL_API=info
```

#### Environment variables file

The third option to set the environment variables is via a text file.

```
DSH_CLI_LOG_LEVEL=debug
DSH_CLI_LOG_LEVEL_API=info
```

Be sure that you do not use spaces around the `=` sign and that you do not use quotes around
the value.

The dsh tool will check the current working directory for a file named `.dsh_cli.env` and if it
exists it will set the environment variables defined in it. You can also specify an alternative
file via the command line argument:

```
> dsh platforms --env-var-file my-settings.env
```

### Environment variables

The following table describes all environment variables.


<table>
    <tr valign="top">
        <th align="left">variable</th>
        <th align="left">description</th>
    </tr>
    <tr valign="top">
        <td><code>DSH_API_PLATFORMS_FILE</code></td>
        <td>
            Set this environment variable to override the default list of available platforms.
            The value of the environment variable must be the name 
            of the alternative platforms file. It can either be an absolute file name, 
            or a relative file name from the working directory. 
            When this environment variable is set, the normal list of default platforms 
            will <em>not</em> be included. If you need these too, make sure that you also 
            include the default platforms in your platforms file.
            See the bottom of this page for more information.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_AUTHENTICATION</code></td>
        <td>
            This environment variable specifies the authentication method that will be used
            to access the resource management api. The allowed values are <code>robot</code> and 
            <code>single-sign-on</code> (<code>sso</code>). If this variable is not provided, 
            the value from the settings file will be used, if it exists. Else, the default value 
            will be <code>single-sign-on</code> when the cli tool is run interactive 
            (<code>stdin</code> is a terminal) and <code>robot</code> if not.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_BROWSER</code></td>
        <td>
            This environment variable specifies whether the cli tool will try to automatically 
            open a browser (e.g. for authentication or to open the console) or will only instruct 
            the user to open it. The allowed values are <code>instruct</code> and 
            <code>open</code>. If this variable is not provided, the value from the settings 
            file will be used, if it exists. Else, the default value will be <code>open</code> 
            when the cli tool is run interactive (<code>stdin</code> is a terminal) and
            <code>instruct</code> if not.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_CSV_QUOTE</code></td>
        <td>
            This environment variable specifies the quote character that will be used 
            when printing csv data. If this variable is not provided, the value from the 
            settings file will be used. The default setting is not to use any quote characters.
            Note that the <code>dsh</code> tool will fail when the generated output already 
            contains the quote character.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_CSV_SEPARATOR</code></td>
        <td>
            This environment variable specifies the separator string that will be used 
            when printing csv data. If this variable is not provided, the value from the 
            settings file will be used. The default separator is <code>","</code> (comma).
            Note that the <code>dsh</code> tool will fail when the generated output already 
            contains the csv separator string.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_DRY_RUN</code></td>
        <td>
            If this environment variable is set (to any value) the <code>dsh</code> tool will not 
            call any api operations that could potentially make changes, like delete, create or 
            change. The input parameters will be validated and checked.
            The same effect can be accomplished via the <code>--dry-run</code>
            command line argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_ENV_FILE</code></td>
        <td>
            This environment variable specifies the location of a file that defines values for the
            environment variables used by the dsh tool. Variables defined in this file will 
            override the values of genuine environment variables set by the os shell, but can  
            themselves be overridden by values defined using the <code>--environment-variable</code>
            command line argument(s). Note that when the <code>--env-var-file</code> command line 
            argument is provided, the environment variable <code>DSH_CLI_ENV_FILE</code> will not 
            be used. The default location is <code>.dsh_cli.env</code> in the current working 
            directory. This environment variable itself cannot be overridden via the 
            <code>--environment-variable</code> command line argument, nor can it be defined 
            in the file itself.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_ERROR_COLOR</code></td>
        <td>
            This environment variable specifies the color to be used when printing error messages. 
            If this variable is not set, the settings file will be checked for the 
            <code>error-color</code> entry. Else the default error color <code>red</code> 
            will be used. When you specify the value <code>normal</code>, 
            no color formatting will be applied and the terminal's default will be used.
            The supported colors are: <code>normal</code> (terminal default), <code>black</code>,
            <code>blue</code>, <code>cyan</code>, <code>green</code>, <code>magenta</code>, 
            <code>red</code>, <code>white</code> and <code>yellow</code>.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_ERROR_STYLE</code></td>
        <td>
            This environment variable specifies the styling to be used when printing error 
            messages. If this variable is not set, the settings file will be checked for the 
            <code>error-style</code> entry. Else the default style <code>bold</code> will be used.
            When you specify the value <code>normal</code>, no style formatting will be applied 
            and the terminal's default will be used.
            The supported styles are: <code>normal</code> (no styling), <code>bold</code>, 
            <code>dim</code>, <code>italic</code>, <code>underline</code> and <code>reverse</code>.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_EXPIRATION</code></td>
        <td> 
            Use this environment variable to specify the number of days used to check if some 
            resource is about to expire. If this variable is not set, the settings file will be 
            checked for the <code>expiration</code> entry. Else the default value <code>30</code> 
            will be used.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_HOME</code></td>
        <td> 
            Use this environment variable to change the location where <code>dsh</code> 
            stores its settings and targets information. 
            The default location is <code>$HOME/.dsh_cli</code>.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_LABEL_COLOR</code></td>
        <td>
            This environment variable specifies the color to be used when printing 
            table headers and labels. 
            If this variable is not set, the settings file will be checked for the 
            <code>label-color</code> entry. Else the default color <code>blue</code> will be used.
            See environment variable <code>DSH_CLI_ERROR_COLOR</code> for the supported colors.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_LABEL_STYLE</code></td>
        <td>
            This environment variable specifies the styling to be used when printing 
            table headers and labels. 
            If this variable is not set, the settings file will be checked for the 
            <code>label-style</code> entry. Else the default value <code>bold</code> will be used.
            See environment variable <code>DSH_CLI_ERROR_STYLE</code> for the supported styles.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_LOG_COLOR</code></td>
        <td>
            This environment variable specifies the color to be used when printing 
            logging information. 
            If this variable is not set, the settings file will be checked for the 
            <code>log-color</code> entry. Else the default color <code>red</code> will be used.
            See environment variable <code>DSH_CLI_ERROR_COLOR</code> for the supported colors.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_LOG_LEVEL</code></td>
        <td> 
            Use this environment variable to set the log level of the <code>dsh</code> tool.
            The available log levels are:
            <ul>
              <li><code>off</code> - logging is off,</li>
              <li><code>error</code> - only errors will be logged,</li>
              <li><code>warn</code> - warnings and errors will be logged,</li>
              <li><code>info</code> - high level info, warnings and errors will be logged,</li>
              <li><code>debug</code> - debug info, high level info, warnings and errors 
                will be logged,</li>
              <li><code>trace</code> - tracing info, debug info, high level info, warnings 
                and errors will be logged.</li>
            </ul>
            If this argument is not provided, the settings file will be checked. 
            When the <code>--log-level</code> command line argument is provided this will override
            this environment variable or the value in the settings file.
            The default log level is <code>error</code>.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_LOG_LEVEL_API</code></td>
        <td> 
            Use this environment variable to set the log level for the functions 
            in the library crate <code>dsh_api</code>, that supports the <code>dsh</code> tool.
            For the available log levels see the description of the 
            <code>DSH_CLI_LOG_LEVEL</code> environment variable.<br/>
            If this argument is not provided, the settings file will be checked. 
            When the <code>--log-level-api</code> command line argument is provided this will 
            override this environment variable or the value in the settings file.
            The default log level is <code>error</code>.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_LOG_STYLE</code></td>
        <td>
            This environment variable specifies the styling to be used when printing 
            logging information. 
            If this variable is not set, the settings file will be checked for the 
            <code>log-style</code> entry. Else the default value <code>dim</code> will be used.
            See environment variable <code>DSH_CLI_ERROR_STYLE</code> for the supported styles.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_MATCHING_COLOR</code></td>
        <td>
            This environment variable specifies the color to be used when printing matching 
            results for the find functions, e.q. when matching regular expressions. 
            If this variable is not set, the settings file will be checked for the 
            <code>matching-color</code> entry. 
            Else the default color <code>green</code> will be used.
            See environment variable <code>DSH_CLI_ERROR_COLOR</code> for the supported colors.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_MATCHING_STYLE</code></td>
        <td>
            This environment variable specifies the styling to be used when printing matching 
            results for the find functions, e.q. when matching regular expressions. 
            If this variable is not set, the settings file will be checked for the 
            <code>matching-style</code> entry. 
            Else the default value <code>bold</code> will be used.
            See environment variable <code>DSH_CLI_ERROR_STYLE</code> for the supported styles.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_NO_CSV_HEADERS</code></td>
        <td>
            When this environment variables is set (to any value) 
            csv output will not contain headers.
            This environment variable can be overridden via the 
            <code>--no-csv-headers</code> command line argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_NO_ESCAPE</code></td>
        <td>
            When this environment variables is set (to any value) 
            the output will not contain any color or other escape sequences.
            This environment variable can be overridden via the 
            <code>--no-color</code> or <code>--no-ansi</code> command line argument.
            Note that <code>NO_COLOR</code> is an alias for this environment variable.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_OUTPUT_DIRECTORY</code></td>
        <td>
            This environment variable specifies the directory where the output of a command will 
            be written to. If this variable is not provided, the value from the settings file 
            will be used. Else, the current working directory will be used. This environment 
            variable can be overridden via the <code>--output-directory</code> command line 
            argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_OUTPUT_FORMAT</code></td>
        <td>
            This option specifies the format used when printing the output. 
            If this argument is not provided, the value from the settings file will be used. 
            Else, when <code>stdout</code> is a terminal the default 
            <code>table</code> will be used, or if <code>stdout</code> is not a terminal 
            the value <code>json</code> will be used.
            The supported values are:
            <ul>
                <li><code>csv</code> - output will be formatted as comma separated values,</li>
                <li><code>json</code> - output will be in json format,</li>
                <li><code>json-compact</code> - output will be in compact json format,</li>
                <li><code>plain</code> - output will be formatted as plain text,</li>
                <li><code>quiet</code> - no output will be generated,</li>
                <li><code>table</code> - output will be formatted as a table with borders,</li>
                <li>
                    <code>table-no-border</code> - output will be formatted as a table 
                    without borders,
                </li>
                <li><code>toml</code> - output will be in toml format,</li>
                <li><code>toml-compact</code> - output will be in compact toml format,</li>
                <li><code>yaml</code> - output will be in yaml format.</li>
            </ul>
            This environment variable can be overridden via the 
            <code>--output-format</code> (or <code>-o</code>) command line argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_PASSWORD</code></td>
        <td>
            This environment variable specifies the secret robot password for the robot 
            authentication method. Note that when the environment variable
            <code>DSH_CLI_PASSWORD_FILE</code> or the <code>--robot-password-file</code> 
            command line argument is provided, this environment variable will not be used. 
            For better security, consider using one of these two options instead of 
            defining <code>DSH_CLI_PASSWORD</code>
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_PASSWORD_FILE</code></td>
        <td>
            This environment variable specifies a file containing the robot password for the 
            robot authentication method. Note that when the <code>--password-file</code> 
            command line argument is provided, this environment variable will not be used. 
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_PLATFORM</code></td>
        <td>
            This environment variable specifies the target platform for which commands will be 
            executed. The supported platforms are:
            <ul>
                <li>
                    <code>np-aws-lz-dsh / nplz</code> - 
                    Staging platform for KPN internal tenants,
                </li>
                <li>
                    <code>poc-aws-dsh / poc</code> - 
                    Staging platform for non KPN tenants,
                </li>
                <li>
                    <code>prod-aws-dsh / prod</code> - 
                    Production platform for non KPN tenants,
                </li>
                <li>
                    <code>prod-aws-lz-dsh / prodlz</code> - 
                    Production platform for KPN internal tenants,
                </li>
                <li>
                    <code>prod-aws-lz-laas / prodls</code> - 
                    Production platform for logstash as a service,
                </li>
                <li>
                    <code>prod-azure-dsh / prodaz</code> - 
                    Production platform for non KPN tenants.
                </li>
            </ul>
            This environment variable can be overridden via the 
            <code>--platform</code> (or <code>-p</code>) command line argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_QUIET</code></td>
        <td>
            When this environment variable is set (to any value) the <code>dsh</code> tool 
            will run in quiet mode, meaning that no output will be produced to the terminal 
            (<code>stdout</code> and <code>stderr</code>).
            This environment variable can be overridden via the 
            <code>--quiet</code> (or <code>-q</code>) command line argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_SHOW_EXECUTION_TIME</code></td>
        <td>
            When this environment variable is set (to any value) the execution time of the 
            executed function will be shown, in milliseconds.
            The execution time will also be shown when the verbosity level is set to 
            <code>high</code>. This environment variable can be overridden via the 
            <code>--show-execution-time</code> command line argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_STDERR_COLOR</code></td>
        <td>
            This environment variable specifies the color to be used when printing explanations 
            and metadata. 
            If this variable is not set, the settings file will be checked for the 
            <code>stderr-color</code> entry. Else the default color for the terminal will be used.
            See environment variable <code>DSH_CLI_ERROR_COLOR</code> for the supported colors.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_STDERR_STYLE</code></td>
        <td>
            This environment variable specifies the styling to be used when printing explanations 
            and metadata. 
            If this variable is not set, the settings file will be checked for the 
            <code>stderr-style</code> entry. Else the default value <code>dim</code> will be used.
            See environment variable <code>DSH_CLI_ERROR_STYLE</code> for the supported styles.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_STDOUT_COLOR</code></td>
        <td>
            This environment variable specifies the color to be used when printing results. 
            If this variable is not set, the settings file will be checked for the 
            <code>stdout-color</code> entry. Else the default color for the terminal will be used.
            See environment variable <code>DSH_CLI_ERROR_COLOR</code> for the supported colors.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_STDOUT_STYLE</code></td>
        <td>
            This environment variable specifies the styling to be used when printing results. 
            If this variable is not set, the settings file will be checked for the 
            <code>stdout-style</code> entry. Else the default value <code>normal</code> 
            (no styling) will be used.
            See environment variable <code>DSH_CLI_ERROR_STYLE</code> for the supported styles.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_SUPPRESS_EXIT_STATUS</code></td>
        <td>
            If this environment variable is set (to any value) the <code>dsh</code> tool will  
            always return exit status 0, even when an error has occurred. 
            This can be useful in scripting environments.
            The same effect can be accomplished via the <code>--suppress-exit-code</code>
            command line argument or the <code>suppress-exit-status</code> setting.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_TARGET_COLOR</code></td>
        <td>
            This environment variable specifies the color to be used when printing target 
            identifiers. If this variable is not set, the settings file will be checked for the 
            <code>target-color</code> entry. Else the default color for the terminal will be used.
            See environment variable <code>DSH_CLI_ERROR_COLOR</code> for the supported colors.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_TARGET_STYLE</code></td>
        <td>
            This environment variable specifies the styling to be used when printing target 
            identifiers. If this variable is not set, the settings file will be checked for the 
            <code>target-style</code> entry. Else the default value <code>normal</code> 
            (no styling) will be used.
            See environment variable <code>DSH_CLI_ERROR_STYLE</code> for the supported styles.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_TENANT</code></td>
        <td>
            This environment variable specifies the target tenant for which commands will be 
            executed. This environment variable can be overridden via the 
            <code>--tenant</code> (or <code>-t</code>) command line argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_TERMINAL_WIDTH</code></td>
        <td>
            When this environment variable is set it will define the maximum terminal width.
            This environment variable can be overridden via the 
            <code>--terminal-width</code> command line argument.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_VERBOSITY</code></td>
        <td>
            If this option is provided, it will set the verbosity level. 
            The default verbosity setting is <code>low</code>.
            The supported verbosity levels are:
            <ul>
                <li><code>off</code> - no logging will be printed,</li> 
                <li><code>low</code> - only error messages will be printed,</li>
                <li><code>medium</code> - some info will be printed,</li>
                <li><code>high</code> - all info will be printed.</li>
            </ul>
            This environment variable can be overridden via the 
            <code>--verbosity</code> (or <code>-v</code>) command line argument.
            Also, when the environment variable <code>DSH_CLI_QUIET</code> is set
            or the command line argument <code>--quiet</code> is provided, nothing will be printed.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_WARNING_COLOR</code></td>
        <td>
            This environment variable specifies the color to be used when printing warnings. 
            If this variable is not set, the settings file will be checked for the 
            <code>warning-color</code> entry. Else the default color <code>blue</code> will be 
            used. See environment variable <code>DSH_CLI_ERROR_COLOR</code> for the supported 
            colors.
        </td>
    </tr>
    <tr valign="top">
        <td><code>DSH_CLI_WARNING_STYLE</code></td>
        <td>
            This environment variable specifies the styling to be used when printing warnings. 
            If this variable is not set, the settings file will be checked for the 
            <code>warning-style</code> entry. Else the default value <code>bold</code> will be 
            used. See environment variable <code>DSH_CLI_ERROR_STYLE</code> for the supported 
            styles.
        </td>
    </tr>
    <tr valign="top">
        <td><code>NO_COLOR</code></td>
        <td>
            When this environment variables is set (to any value) 
            the output will not contain any color or other escape sequences.
            This environment variable can be overridden via the 
            <code>--no-color</code> or <code>--no-ansi</code> command line argument.
            Note that <code>DSH_CLI_NO_ESCAPE</code> is an alias for this environment variable.
        </td>
    </tr>
    <tr valign="top">
        <td><code>RUST_LOG</code></td>
        <td>
            You can configure the log levels and settings for the <code>dsh</code> tool entirely 
            via the environment variables <code>DSH_CLI_LOG_LEVEL</code> and 
            <code>DSH_CLI_LOG_LEVEL_API</code>, 
            the options <code>--log-level</code> and <code>--log-level-api</code> 
            and via the <code>dsh setting</code> command line functions.
            Since the <code>dsh</code> tool depends on the  
            <a href="https://docs.rs/env_logger/latest/env_logger"><code>env_logger</code></a> 
            crate for its logging it also recognizes log configuration via the 
            <code>RUST_LOG</code> environment variable.
            Although the use of this variable is not recommended, 
            there might be situations when this can be useful.
            See the crate's <code>GitHub</code> repository for more information.
        </td>
    </tr>

</table>

[Settings and targets &#x2192;](settings-targets.md)
