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
• 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

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

• 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.)