# Environment Variables

The command-line client and the client bindings use a set of environment variables to communicate with the API server and to store state on the current default project and directory. These settings are set when you run `dx login` and can be changed through other `dx` commands. To display the active settings in human-readable format, use the `dx env` command:

```shell
$ dx env
Auth token used         adLTkSNkjxoAerREqbB1dVkspQzCOuug
API server protocol     https
API server host         api.dnanexus.com
API server port         443
Current workspace       project-9zVpbQf4Zg2641v5BGY00001
Current workspace name  "Scratch Project"
Current folder          /
Current user            alice
```

To print the bash commands for setting the environment variables to match what `dx` is using, you can run the same command with the `--bash` flag.

```shell
$ dx env --bash
export DX_SECURITY_CONTEXT='{"auth_token_type": "bearer", "auth_token": "adLTkSNkjxoAerREqbB1dVkspQzCOuug"}'
export DX_APISERVER_PROTOCOL=https
export DX_APISERVER_HOST=api.dnanexus.com
export DX_APISERVER_PORT=443
export DX_PROJECT_CONTEXT_ID=project-9zVpbQf4Zg2641v5BGY00001
```

Running a `dx` command from the command-line does not (and cannot) overwrite your shell's environment variables. The environment variables are stored in the `~/.dnanexus_config/environment.json` file.

## Configuration File Prioritization

The following is an ordered list of which DNAnexus utilities load values from configuration sources:

1. Command line options (if available)
2. Environment variables already set in the shell
3. `~/.dnanexus_config/environment.json` (`dx` configuration file)
4. Hardcoded defaults

### Overriding the `dx` Configuration File

The `dx` command **always** prioritizes the environment variables that are set in the shell. This means that if you have set your environment variable for `DX_SECURITY_CONTEXT` and then use `dx login` to log in as a different user, it still uses the original environment variable. When not run in a script, it prints a warning to `stderr` whenever the environment variables and its stored state have a mismatch. To get out of this situation, the best approach is often to run `source ~/.dnanexus_config/unsetenv`. Setting environment variables is generally used within a shell script or as part of a job environment in the cloud.

In the interaction below, environment variables have already been set, but the user then uses `dx` to log in which is still overridden by the shell's environment variables.

```shell
$ dx ls -l
Project: Sample Project (project-9zVpbQf4Zg2641v5BGY00001)
Folder : /
<Contents of Sample Project>
$ dx login
Acquiring credentials from https://auth.dnanexus.com
Username: alice
Password:

Note: Use "dx select --level VIEW" or "dx select --public" to select from
projects for which you only have VIEW permissions.

Available projects:
0) SAM importer test (CONTRIBUTE)
1) Scratch Project (ADMINISTER)
2) Mouse (ADMINISTER)

Pick a numbered choice [1]: 2
Setting current project to: Mouse
$ dx ls
WARNING: The following environment variables were found to be different than the
values last stored by dx: DX_SECURITY_CONTEXT, DX_PROJECT_CONTEXT_ID
To use the values stored by dx, unset the environment variables in your shell by
running "source ~/.dnanexus_config/unsetenv". To clear the dx-stored values,
run "dx clearenv".
Project: Sample Project (project-9zVpbQf4Zg2641v5BGY00001)
Folder : /
<Contents of Sample Project>
$ source ~/.dnanexus_config/unsetenv
$ dx ls -l
Project: Mouse (project-9zVpbQf4Zg2641v5BGY00002)
Folder : /
<Contents of Mouse>
```

#### Clearing dx-set Variables

If you instead want to discard the values which `dx` has stored, the command `dx clearenv` removes the `dx`-generated configuration file `~/.dnanexus_config/environment.json` for you.

### Command Line Options

Most `dx` commands have the following additional flags to temporarily override the values of the respective variables.

```shell
$ dx --env-help
usage: dx command ... [--apiserver-host APISERVER_HOST]
                      [--apiserver-port APISERVER_PORT]
                      [--apiserver-protocol APISERVER_PROTOCOL]
                      [--project-context-id PROJECT_CONTEXT_ID]
                      [--workspace-id WORKSPACE_ID]
                      [--security-context SECURITY_CONTEXT]
                      [--auth-token AUTH_TOKEN]

optional arguments:
  --apiserver-host APISERVER_HOST
                        API server host
  --apiserver-port APISERVER_PORT
                        API server port
  --apiserver-protocol APISERVER_PROTOCOL
                        API server protocol (http or https)
  --project-context-id PROJECT_CONTEXT_ID
                        Default project or project context ID
  --workspace-id WORKSPACE_ID
                        Workspace ID (for jobs only)
  --security-context SECURITY_CONTEXT
                        JSON string of security context
  --auth-token AUTH_TOKEN
                        Authentication token
```

For example, you can temporarily override the current default project used:

```shell
$ dx env --project-context-id project-B0VK6F6gpqG6z7JGkbqQ000Q
Auth token used         R54BN6Ws6Zl3Y0VqBA9o1qweUswYW5o4
API server protocol     https
API server host         api.dnanexus.com
API server port         443
Current workspace       project-B0VK6F6gpqG6z7JGkbqQ000Q
Current folder          /
```