# atmos terraform output

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

## Usage

Execute the `terraform output` command like this:

```shell
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.

:::info 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`:

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

These settings can also be controlled via environment variables:

```shell
export ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE=true
```

## Examples

### Show All Outputs

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

### Get Specific Output

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

### JSON Format

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

### Raw Output

```shell
# 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)

```shell
# 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:

```yaml
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:

```shell
# 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:

```shell
# 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
```

:::note 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.
  ```shell
  # 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) |
  ```shell
  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.
  ```shell
  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`.
  ```shell
  # 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.
  ```shell
  # 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.
  ```shell
  atmos terraform output vpc -s dev --skip-init
  ```
- **`--dry-run` (optional)**

  Show what would be executed without actually running the command.
  ```shell
  atmos terraform output vpc -s dev --dry-run
  ```

## Native Terraform Flags

- **`-json`**

  Output in JSON format.
  ```shell
  atmos terraform output vpc -s dev -json
  ```
- **`-raw`**

  Output raw string value (for single outputs).
  ```shell
  atmos terraform output vpc -s dev -raw vpc_id
  ```
- **`-state=PATH`**

  Path to the state file to read.
  ```shell
  atmos terraform output vpc -s dev -state=terraform.tfstate
  ```

## Related Commands

- [`atmos terraform plan`](/cli/commands/terraform/plan) - Generate execution plan
- [`atmos terraform apply`](/cli/commands/terraform/apply) - Apply changes
- [`atmos terraform init`](/cli/commands/terraform/init) - Initialize working directory