Skip to main content

atmos list stacks

Use this command to list all stacks in your Atmos configuration, optionally filtering by component. View stacks in multiple formats including tables, JSON, YAML, or hierarchical trees with import provenance to understand configuration inheritance.

atmos list stacks --help

Usage​

Execute the list stacks command like this:

atmos list stacks

To view all stacks for a provided component, execute the list stacks command like this:

atmos list stacks -c <component>
tip

Run atmos list stacks --help to see all the available options

Examples​

List all stacks:

atmos list stacks

List stacks for a specific component:

atmos list stacks -c vpc
atmos list stacks --component eks

Output in different formats:

# JSON format
atmos list stacks --format json

# YAML format
atmos list stacks --format yaml

# CSV format
atmos list stacks --format csv

Sort stacks:

# Sort by stack name ascending
atmos list stacks --sort stack:asc

# Sort by component name descending
atmos list stacks --component vpc --sort component:desc

Custom columns:

# Simple field names (auto-generates templates)
atmos list stacks --columns stack

# Named columns with custom templates
atmos list stacks --columns "Name={{ .stack }}"

# When filtering by component, show both stack and component
atmos list stacks --component vpc --columns stack,component

View stacks in tree format:

# Tree view without import details
atmos list stacks --format tree

# Tree view with import provenance (shows inheritance chain)
atmos list stacks --format tree --provenance

# Tree view with provenance for a specific component
atmos list stacks --component vpc --format tree --provenance

Flags​

--component / -c
Filter stacks by component name.
Environment variable: ATMOS_COMPONENT
--format / -f
Output format: table, json, yaml, csv, tsv, tree. Overrides stacks.list.format configuration in atmos.yaml (default: table).
Environment variable: ATMOS_LIST_FORMAT
--columns
Columns to display. Supports simple field names (e.g., stack), named columns with templates (e.g., "Name={{ .stack }}"), or named with field reference (e.g., "MyStack=stack"). Overrides stacks.list.columns configuration in atmos.yaml. Environment variable: ATMOS_LIST_COLUMNS
--sort
Sort by column:order (e.g., stack:asc,component:desc). Multiple sort columns separated by comma.
Environment variable: ATMOS_LIST_SORT
--provenance
Show import provenance in tree format. Only works with --format=tree. Displays the import hierarchy showing which files each stack inherits from.
Environment variable: ATMOS_PROVENANCE
--identity / -i (optional)
Authenticate with a specific identity before listing stacks.
This is required when stack configurations use YAML template functions
(e.g., !terraform.state, !terraform.output) that require authentication.
atmos list stacks --identity my-aws-identity

Environment variable: ATMOS_IDENTITY

Tree Format with Import Provenance​

The tree format provides a hierarchical view of your stacks. When combined with the --provenance flag, it shows the complete import chain for each stack, making it easy to understand configuration inheritance.

Tree Format Structure​

The tree format displays:

  • Stack names as top-level nodes
  • Import hierarchy (when --provenance is enabled) showing the chain of stack configuration files that each stack imports

Import Provenance​

When you enable --provenance, each stack shows its import chain - the sequence of stack configuration files it inherits from. This is particularly useful for:

  • Debugging configuration - See exactly where each stack's configuration comes from
  • Understanding inheritance - Visualize the complete import chain
  • Auditing changes - Track which base configurations affect which stacks
  • Documentation - Generate visual representations of stack dependencies

Example tree output with provenance:

Stacks
│
├── tenant1-ue2-dev
│   ├── stacks/tenant1/ue2/dev
│   ├── stacks/tenant1/ue2/_defaults
│   ├── stacks/tenant1/_defaults
│   └── stacks/_defaults
│
├── tenant1-ue2-staging
│   ├── stacks/tenant1/ue2/staging
│   ├── stacks/tenant1/ue2/_defaults
│   ├── stacks/tenant1/_defaults
│   └── stacks/_defaults

The import chain is shown from most specific (top) to most general (bottom), reflecting how Atmos merges configurations.

When used with --component, the tree shows only stacks that contain the specified component:

atmos list stacks --component vpc --format tree --provenance

This filters the output to show only stacks where the vpc component is defined, along with their import chains.

Configuration​

You can customize the default output format and columns displayed by atmos list stacks in your atmos.yaml:

Default Format​

# atmos.yaml
stacks:
  list:
    format: tree  # Default format: table, json, yaml, csv, tsv, tree

Precedence: CLI --format flag > Config file > Environment variable ATMOS_LIST_FORMAT > Default (table)

Custom Columns​

# atmos.yaml
stacks:
  list:
    format: table
    columns:
      - name: Stack
        value: "{{ .stack }}"
      - name: Namespace
        value: "{{ .vars.namespace }}"
      - name: Tenant
        value: "{{ .vars.tenant }}"
      - name: Environment
        value: "{{ .vars.environment }}"
      - name: Stage
        value: "{{ .vars.stage }}"
note

Column configuration for stacks is under the stacks.list.columns section in atmos.yaml, not components.list.columns.

Available Template Fields​

Column value fields support Go template syntax with access to:

  • .stack - Stack name
  • .vars - Stack variables from component configuration (access fields via .vars.fieldname)
    • .vars.namespace - Namespace variable
    • .vars.tenant - Tenant variable
    • .vars.environment - Environment variable
    • .vars.stage - Stage variable
    • .vars.<any> - Any other variable defined in your stack's vars section
  • .components - Map of components in the stack
  • .file - Stack configuration file path
tip

Variables are extracted from the first component in each stack. Since all components in a stack typically share the same stack-level variables (namespace, tenant, environment, stage), this provides consistent access to stack metadata regardless of which components are defined.

Template Functions​

Columns support template functions for data transformation:

stacks:
  list:
    columns:
      - name: Stack
        value: "{{ .stack }}"
      - name: Namespace
        value: "{{ .vars.namespace | upper }}"
      - name: Region
        value: "{{ .vars.region }}"
      - name: Env
        value: "{{ .vars.stage | upper }}"

Available functions:

  • upper, lower - String case conversion
  • truncate - Truncate string with ellipsis
  • len - Length of arrays/strings
  • join - Join array elements with delimiter
  • toString - Convert value to string
  • ternary - Conditional expression
  • get, getOr, has - Safe map access (e.g., {{ get .vars "region" }})

Override Columns via CLI​

Override configured columns using the --columns flag. The flag supports multiple formats:

Simple field names (auto-generates templates and title-case names):

# Display only stack column
atmos list stacks --columns stack

# When filtering by component, show both
atmos list stacks --component vpc --columns stack,component

Named columns with templates (full control over display name and value):

# Custom column names with templates
atmos list stacks --columns "StackName={{ .stack }}"

# Multiple named columns
atmos list stacks --columns "Name={{ .stack }},Components={{ .components | len }}"

Named columns with field reference (auto-wraps field in template):

# Shorthand: Name=field becomes Name={{ .field }}
atmos list stacks --columns "MyStack=stack"