Environment Variables

The env section in atmos.yaml defines global environment variables that are automatically set for all Atmos operations. Use this to configure tools, inject credentials, or set defaults that apply across your entire project.

You will learn

• Set environment variables once, use everywhere
• Works seamlessly with Atmos profiles for environment-specific configuration
• Supports YAML functions like !env and !exec for dynamic values
• Import dotenv files explicitly with !include
• Variables are merged with system environment (global env can override system, component env overrides global)

Configuration

Configure global environment variables in the env section of your atmos.yaml:

atmos.yaml

env:
  # Get GitHub token dynamically from gh CLI
  GITHUB_TOKEN: !exec gh auth token

  # Static environment variable values
  AWS_SDK_LOAD_CONFIG: "true"
  TF_PLUGIN_CACHE_DIR: /tmp/terraform-plugin-cache

Including Dotenv Files

Use !include to load values from a dotenv file directly into the CLI env section:

atmos.yaml

env: !include .env

Use YAML merge keys when you want to include dotenv values and also define inline overrides. The << key is YAML's merge-key syntax, the same YAML mechanism commonly used with anchors and aliases:

atmos.yaml

env:
  <<: !include .env
  AWS_REGION: us-east-2

Atmos parses .env, .env.*, and *.env files as dotenv key/value files when they are included with !include. The included values become a map, so standard YAML merge behavior applies: keys written directly under env override keys loaded from the dotenv file.

.env

AWS_REGION=us-east-1
AWS_SDK_LOAD_CONFIG=true

atmos.yaml

env:
  <<: !include .env
  AWS_REGION: us-east-2 # Overrides AWS_REGION from .env

Use !include.raw when you need the raw file contents instead of parsed dotenv values.

You can layer multiple dotenv files with a YAML merge sequence:

atmos.yaml

env:
  <<:
    - !include .env.local
    - !include .env
  AWS_REGION: us-east-2

YAML merge sequence precedence is earlier item wins. In the example above, .env.local has higher precedence than .env, so .env.local overrides .env. Keys written directly under env, such as AWS_REGION, override all merged dotenv values.

Local dotenv paths follow the existing !include resolution rules. Use ./ or ../ for paths relative to the YAML file containing the include; bare local paths such as .env follow Atmos' normal current/base-path lookup for includes. Absolute paths are honored.

NOTE:

Atmos does not automatically load dotenv files, and it does not load or execute .envrc files. Dotenv support is explicit through !include.

Pinning Atmos Configuration Per Project

Keys in the global env section that begin with the ATMOS_ prefix configure Atmos itself, not just the tools Atmos runs. When Atmos loads atmos.yaml, it promotes any ATMOS_* variables from the env section into its own process environment before it resolves things like the active profile. This lets you pin a profile per project by committing a dotenv file:

.env

ATMOS_PROFILE=dev

atmos.yaml

env: !include .env

With this in place, running any atmos command in the project uses the dev profile automatically — no --profile flag or exported ATMOS_PROFILE required. The same applies to other Atmos settings such as ATMOS_BASE_PATH.

NOTE:

An exported environment variable always wins: if ATMOS_PROFILE is already set in your shell, the value in the env section is not applied. This keeps ad-hoc overrides (ATMOS_PROFILE=ci atmos …) working as expected.

To pin ATMOS_PROFILE, the env: !include .env must live in your base atmos.yaml (not inside a profile), since it has to be resolved before the profile is selected. Only ATMOS_-prefixed keys are promoted into Atmos' own environment; all other env keys continue to flow only to the tools Atmos runs (Terraform, Helmfile, etc.).

env

A map of environment variable names to values. Values can be literal strings or use YAML functions for dynamic values.

Type: map[string]string

Default: Not set

Precedence

Environment variables are merged in the following order (lowest to highest priority):

Priority	Source	Description
1 (lowest)	System environment	Variables from your shell (os.Environ())
2	Global env in atmos.yaml	Variables defined in CLI configuration
3 (highest)	Component/stack env	Variables defined in stack manifests

This means:

• Global env in atmos.yaml can override system environment variables
• Component-level env in stacks can override global env

Special Handling for Terraform CLI Args

Variables starting with TF_CLI_ARGS_ receive special handling. Instead of replacing, new values are prepended to existing values, allowing you to layer Terraform arguments:

# atmos.yaml
env:
  TF_CLI_ARGS_plan: "-compact-warnings"

# If TF_CLI_ARGS_plan is already set to "-lock=false" in your shell,
# the final value becomes: "-compact-warnings -lock=false"

YAML Functions

The env section supports YAML functions for dynamic values:

Reading from Other Environment Variables

Use !env to read values from the current environment:

env:
  # Copy GH_TOKEN to GITHUB_TOKEN if it exists
  GITHUB_TOKEN: !env GH_TOKEN

  # With a default value if not set
  AWS_PROFILE: !env MY_AWS_PROFILE default

Executing Commands

Use !exec to set values from command output:

env:
  # Get GitHub token from gh CLI
  GITHUB_TOKEN: !exec gh auth token

  # Get AWS account ID
  AWS_ACCOUNT_ID: !exec aws sts get-caller-identity --query Account --output text

Use Cases

GitHub Token for Private Terraform Modules

When using private GitHub repositories as Terraform module sources, set GITHUB_TOKEN:

atmos.yaml

env:
  # Use gh CLI to get token (requires gh auth login)
  GITHUB_TOKEN: !exec gh auth token

This enables Terraform to authenticate when downloading modules:

module "vpc" {
  source = "git::https://github.com/myorg/terraform-aws-vpc.git?ref=v1.0.0"
}

Terraform Plugin Cache

Speed up Terraform operations by caching providers:

atmos.yaml

env:
  TF_PLUGIN_CACHE_DIR: /tmp/terraform-plugin-cache

AWS SDK Configuration

Configure AWS SDK behavior globally:

atmos.yaml

env:
  AWS_SDK_LOAD_CONFIG: "true"
  AWS_RETRY_MODE: "adaptive"
  AWS_MAX_ATTEMPTS: "10"

OpenTofu Configuration

Set OpenTofu-specific environment variables:

atmos.yaml

env:
  TOFU_CLI_CONFIG_FILE: /etc/opentofu/tofurc

Using with Atmos Profiles

The env section becomes powerful when combined with Atmos profiles. Define environment-specific variables in profile configurations:

Local Development Profile

profiles/developer/atmos.yaml

metadata:
  name: developer
  description: Local development with GitHub token from gh CLI

env:
  # Get token from gh CLI for local development
  GITHUB_TOKEN: !exec gh auth token

  # Enable debug logging
  TF_LOG: DEBUG

CI/CD Profile

profiles/ci/atmos.yaml

metadata:
  name: ci
  description: CI/CD pipeline settings

env:
  # In CI, GITHUB_TOKEN is typically already set by the CI system
  # This passes through the existing token from the CI environment
  GITHUB_TOKEN: !env GITHUB_TOKEN

  # CI-specific settings
  TF_IN_AUTOMATION: "true"
  TF_INPUT: "false"

Usage

# Local development - uses gh CLI for GitHub token
atmos --profile developer terraform plan vpc -s prod

# CI/CD - uses existing GITHUB_TOKEN from CI environment
ATMOS_PROFILE=ci atmos terraform apply vpc -s prod --auto-approve

This pattern allows you to:

• Use gh auth token locally (no token management)
• Use CI-provided GITHUB_TOKEN in pipelines (secure, no secrets in config)
• Keep your base atmos.yaml clean of environment-specific settings

Comparison with Stack-Level env

Feature	CLI env (atmos.yaml)	Stack env (stack manifests)
Scope	All Atmos operations	Specific components/stacks
Inheritance	From profiles	From stack imports
Use case	Global tooling config	Component-specific config
Template support	Yes	Yes

When to Use Which

Use CLI env for:

• Tool configuration (GITHUB_TOKEN, TF_PLUGIN_CACHE_DIR)
• SDK settings (AWS_SDK_LOAD_CONFIG)
• CI/CD automation flags (TF_IN_AUTOMATION)

Use Stack env for:

• Cloud provider profiles (AWS_PROFILE)
• Region-specific settings (AWS_REGION)
• Component-specific debugging (TF_LOG)

Examples

Complete Development Setup

atmos.yaml

env:
  # GitHub authentication for private modules
  GITHUB_TOKEN: !exec gh auth token

  # Terraform caching
  TF_PLUGIN_CACHE_DIR: /tmp/terraform-plugin-cache

  # AWS configuration
  AWS_SDK_LOAD_CONFIG: "true"

CI/CD Pipeline Setup

profiles/ci/atmos.yaml

env:
  # Automation mode
  TF_IN_AUTOMATION: "true"
  TF_INPUT: "false"

  # Use existing CI tokens
  GITHUB_TOKEN: !env GITHUB_TOKEN

  # Disable color for log parsing
  NO_COLOR: "1"

Multi-Cloud Setup

atmos.yaml

env:
  # AWS
  AWS_SDK_LOAD_CONFIG: "true"

  # Azure
  ARM_USE_CLI: "true"

  # GCP
  GOOGLE_CLOUD_PROJECT: my-project-id

See Also

• Environment Variables - Complete reference for all Atmos CLI environment variables
• Global Flags - Flag reference with environment variable equivalents
• Profiles - Environment-specific configuration overrides
• Stack Environment Variables - Component-level environment variables
• Commands - Custom commands with environment variables
• YAML Functions - Dynamic value functions (!env, !exec, !store, etc.)