# !env

The `!env` Atmos YAML function is used to retrieve environment variables
from stack manifest `env:` sections or OS environment variables, and assign them to sections in Atmos stack manifests.

## Usage

The `!env` function can be called with either one or two parameters:

```yaml
  # Get the value of an environment variable.
  # If the environment variable is not present in the environment, `null` will be assigned
  !env <env-var-name>

  # Get the value of an environment variable.
  # If the environment variable is not present in the environment, the `default-value` will be assigned
  !env <env-var-name> <default-value>
```

## Arguments

- **`env-var-name`**

  Environment variable name
- **`default-value`**
  (Optional) Default value to use if the environment variable is not present in the environment

If the function is called with one argument (the name of the environment variable), and the environment variable is
not present, `null` will be assigned to the corresponding section in the Atmos manifest.

If the function is called with two arguments (the name of the environment variable and the default value), and the
environment variable is not present, the default value will be assigned to the corresponding section in the Atmos manifest.

## Resolution Order

The `!env` function follows this resolution order when looking up environment variable values:

1. **Stack manifest `env:` sections** - Checks the component's merged `env:` section (which includes values from globals, imports, base components, and the component itself)
2. **OS environment variables** - Falls back to operating system environment variables if not found in stack manifests
3. **Default value** - Uses the provided default value if the variable is not found in either location

This means you can define environment variables in your stack manifests and reference them using `!env`:

```yaml
# globals.yaml
env:
  APP_ENVIRONMENT: "production"
  API_BASE_URL: "https://api.example.com"

# In your component stack
components:
  terraform:
    my-app:
      env:
        # This will resolve to "production" from globals.yaml
        ENVIRONMENT: !env APP_ENVIRONMENT

        # This will resolve to "https://api.example.com" from globals.yaml
        API_URL: !env API_BASE_URL
```

:::info
The `env:` section follows the standard Atmos merge priority:
`GlobalEnv` \< `BaseComponentEnv` \< `ComponentEnv` \< `ComponentOverridesEnv`

This means values defined at the component level will override values from globals.
:::

:::note Type-Aware Merging
Atmos supports type-aware merging of YAML functions and concrete values, allowing them to coexist in the inheritance chain without type conflicts.
See the full explanation: [YAML Function Merging](/reference/yaml-function-merging)
:::

## Limitations

**Single-Pass Processing**: YAML functions are processed in a single pass. This means `!env` cannot reference environment variables that are defined by other YAML functions in the same component section.

For example, this **will NOT work**:

```yaml
components:
  terraform:
    my-app:
      env:
        # FIRST_LEVEL resolves correctly from globals
        FIRST_LEVEL: !env FOO

        # ❌ SECOND_LEVEL will NOT resolve - it will remain as the literal string "!env FOO"
        # because FIRST_LEVEL hasn't been processed yet when this is evaluated
        SECOND_LEVEL: !env FIRST_LEVEL
```

However, you **can** reference env variables from parent contexts (globals, imports, base components):

```yaml
# globals.yaml
env:
  FOO: "bar"

# component stack
components:
  terraform:
    my-app:
      env:
        # ✅ This works - FOO exists in the merged env section from globals
        MY_VAR: !env FOO
```

## Examples

### Using Stack Manifest Environment Variables

```yaml
# globals.yaml
env:
  DATABASE_HOST: "db.prod.example.com"
  DATABASE_PORT: "5432"

# dev.yaml
components:
  terraform:
    my-service:
      env:
        # Reference env variables defined in globals
        DB_HOST: !env DATABASE_HOST
        DB_PORT: !env DATABASE_PORT
      vars:
        # Can also use in vars section
        connection_string: !env DATABASE_HOST
```

### Using OS Environment Variables

```yaml
vars:
  # `api_key` will be set to `null` if the OS environment variable `API_KEY` is not present
  api_key: !env API_KEY
  # `app_name` will be set to the default value `my-app` if the OS environment variable `APP_NAME` is not present
  app_name: !env APP_NAME my-app

settings:
  # `provisioned_by_user` will be set to `null` if the OS environment variable `ATMOS_USER` is not present
  provisioned_by_user: !env ATMOS_USER
```

### Mixed Usage (Stack Manifests + OS Environment)

```yaml
# globals.yaml
env:
  REGION: "us-east-1"

# component stack
components:
  terraform:
    my-app:
      env:
        # From stack manifest globals
        AWS_REGION: !env REGION

        # From OS environment (with default)
        AWS_PROFILE: !env AWS_PROFILE default-profile
```

## Handling default values with spaces

If you need to provide default values with spaces, enclose them in double quotes and use single quotes around the whole expression.

For example:

```yaml
  # `app_name` will be set to the default value `my app` if the environment variable `APP_NAME` is not present in the environment
  app_name: !env 'APP_NAME "my app"'

  # `app_description` will be set to the default value `my app description` if the environment variable `APP_DESCRIPTION` is not present in the environment
  app_description: !env 'APP_DESCRIPTION "my app description"'
```

**Handling Nested Quotes**

If your default value contains both single and double quotes, wrap the entire function call in single quotes while keeping any required double quotes inside the expression:

```yaml
# Use single quotes to wrap expressions containing double quotes
config_path: !env 'CONFIG_PATH "/etc/app/config.json"'

# Keep default values with mixed quotes readable by surrounding the expression with single quotes
api_endpoint: !env 'API_URL "https://api.example.com/v1"'
```

:::tip
Detailed escaping guidance (including bracket-notation examples) lives in the [!terraform.output documentation](/functions/yaml/terraform.output#handling-yq-expressions-with-bracket-notation-and-quotes). The same rules apply to `!env` because all YAML functions share the parser.
:::

:::tip
You can use [Atmos Stack Manifest Templating](/templates) in the environment variable names and default values when calling the `!env` YAML function.
Atmos processes the templates first, and then executes the `!env` function, allowing you to provide the parameters to
the function dynamically.
:::