atmos terraform output

Use this command to read Terraform output values for an Atmos component in a stack from the state file.

atmos terraform output --help

Usage

Execute the terraform output command like this:

atmos terraform output <component> -s <stack> [options]

This command reads output values from the Terraform state file and prints them. Output values are useful for passing information between different Terraform configurations or to external systems.

Atmos Behavior

Atmos provides standard setup for this command including automatic terraform init, workspace selection, and variable file generation. The output retrieval itself is handled by native Terraform.

Configuration

Configure default behavior for terraform output in your atmos.yaml:

components:
  terraform:
    # Auto-generate backend configuration
    auto_generate_backend_file: true

These settings can also be controlled via environment variables:

export ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE=true

Examples

Show All Outputs

# Display all outputs for a component
atmos terraform output vpc -s dev

Get Specific Output

# Get a specific output value
atmos terraform output vpc -s dev vpc_id

JSON Format

# Get outputs in JSON format
atmos terraform output vpc -s dev -json

Raw Output

# Get raw output value (useful for scripts)
atmos terraform output vpc -s dev -raw vpc_id

GitHub Actions Integration

The --format=github option is specifically designed for GitHub Actions workflows. It formats outputs using heredoc syntax for multiline values and writes to:

1. --output-file if specified
2. $GITHUB_OUTPUT environment variable if set
3. stdout otherwise (useful for previewing output locally)

# Automatically writes to $GITHUB_OUTPUT in GitHub Actions
atmos terraform output vpc -s dev --format=github

# Preview output locally (writes to stdout when $GITHUB_OUTPUT is not set)
atmos terraform output vpc -s dev --format=github

# Export a single output to GitHub Actions
atmos terraform output vpc -s dev vpc_id --format=github

# Or specify a custom output file
atmos terraform output vpc -s dev --format=github --output-file=outputs.txt

Example GitHub Actions workflow:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Get Terraform Outputs
        id: outputs
        run: atmos terraform output vpc -s dev --format=github

      - name: Use Outputs
        run: |
          echo "VPC ID: ${{ steps.outputs.outputs.vpc_id }}"
          echo "Subnets: ${{ steps.outputs.outputs.private_subnet_ids }}"

Export All Outputs with --format

The --format flag enables exporting all outputs in various formats, which is particularly useful for CI/CD workflows:

# Export for GitHub Actions (writes to $GITHUB_OUTPUT automatically)
atmos terraform output app -s preview --skip-init --format=github

# Export as environment variables for older GitHub Actions syntax
atmos terraform output app -s preview --skip-init --format=env --output-file=$GITHUB_OUTPUT

# Export as bash exports for shell sourcing
eval $(atmos terraform output vpc -s prod --format=bash)

# Save as .env file
atmos terraform output app -s staging --format=dotenv --output-file=.env

# Export as JSON for processing
atmos terraform output app -s staging --format=json --output-file=outputs.json

# Export as HCL for Terraform locals
atmos terraform output vpc -s prod --format=hcl --output-file=vpc_outputs.auto.tfvars

# Export as CSV for spreadsheets
atmos terraform output app -s prod --format=csv --output-file=outputs.csv

# Export with UPPERCASE keys for environment variables
atmos terraform output vpc -s prod --format=env --uppercase

Format a Single Output

You can combine the --format flag with a specific output name to format a single value:

# Get a single output as JSON (useful for complex values like maps/lists)
atmos terraform output vpc -s dev vpc_config --format=json

# Get a single output as YAML
atmos terraform output vpc -s dev vpc_config --format=yaml

# Export a single value to GitHub Actions
atmos terraform output app -s preview url --format=env --output-file=$GITHUB_OUTPUT

Complex Values

For single outputs that contain complex values (maps or lists), only structured formats (json, yaml, hcl) are supported. Scalar-only formats (env, dotenv, bash, csv, tsv) will return an error for complex values.

Arguments

component (required)

Atmos component name.

output_name (optional)

Name of a specific output to retrieve. When omitted, all outputs are returned.

# All outputs
atmos terraform output vpc -s dev

# Single output
atmos terraform output vpc -s dev vpc_id

Flags

--stack / -s (required)

Atmos stack name where the component is defined.

--format / -f (optional)

Output format for exports. When specified, retrieves outputs and formats them instead of passing through to native Terraform. Works with both all outputs or a single named output.

Supported formats:

Format	Output Style	Use Case
json	{"key": "value"}	Machine parsing, piping to jq
yaml	key: value	Human-readable, config files
hcl	key = "value"	Terraform locals or tfvars files
env	key=value	Environment variables
dotenv	key='value'	.env files with quoting
bash	export key='value'	Shell sourcing with eval $(...)
csv	key,value	Spreadsheets, data processing
tsv	key<tab>value	Tab-delimited for easy parsing
github	key=value or heredoc	GitHub Actions step outputs (writes to $GITHUB_OUTPUT if set, otherwise stdout)

atmos terraform output vpc -s dev --format=env

Environment variable: ATMOS_TERRAFORM_OUTPUT_FORMAT

--output-file / -o (optional)

Write output to a file instead of stdout. Appends to the file if it exists.

atmos terraform output vpc -s dev --format=env --output-file=$GITHUB_OUTPUT

Environment variable: ATMOS_TERRAFORM_OUTPUT_FILE

--uppercase / -u (optional)

Convert output keys to uppercase. Useful for environment variable exports where vpc_id becomes VPC_ID.

# Export with uppercase keys
atmos terraform output vpc -s dev --format=env --uppercase

# Output: VPC_ID=vpc-123, SUBNET_ID=subnet-456

Environment variable: ATMOS_TERRAFORM_OUTPUT_UPPERCASE

--flatten (optional)

Flatten nested maps and arrays into flat key/value pairs using underscore as separator. Useful for exporting nested terraform outputs as individual environment variables.

# Flatten nested maps
atmos terraform output vpc -s dev --format=env --flatten

# Input: {"config": {"host": "localhost", "port": 3000}}
# Output: config_host=localhost, config_port=3000

# Flatten arrays with numeric indices
# Input: {"subnets": [{"id": "subnet-1"}, {"id": "subnet-2"}]}
# Output: subnets_0_id=subnet-1, subnets_1_id=subnet-2

# Combine with --uppercase for standard ENV_VAR naming
atmos terraform output vpc -s dev --format=env --flatten --uppercase

# Output: CONFIG_HOST=localhost, CONFIG_PORT=3000

Environment variable: ATMOS_TERRAFORM_OUTPUT_FLATTEN

--skip-init (optional)

Skip running terraform init before executing the command.

atmos terraform output vpc -s dev --skip-init

--dry-run (optional)

Show what would be executed without actually running the command.

atmos terraform output vpc -s dev --dry-run

Native Terraform Flags

-json

Output in JSON format.

atmos terraform output vpc -s dev -json

-raw

Output raw string value (for single outputs).

atmos terraform output vpc -s dev -raw vpc_id

-state=PATH

Path to the state file to read.

atmos terraform output vpc -s dev -state=terraform.tfstate

Related Commands

• atmos terraform plan - Generate execution plan
• atmos terraform apply - Apply changes
• atmos terraform init - Initialize working directory