Skip to main content

atmos list

Use these subcommands to list sections of Atmos configurations.

Configure Stacks

Learn how to configure stacks, components, and the list command column customization.

Usage​

atmos list --help

Atmos provides a powerful feature to customize the columns displayed by various atmos list commands (e.g., atmos list stacks, atmos list components, atmos list workflows). This allows you to tailor the tabular output to show precisely the information you need for different contexts.

Column customization is configured within your atmos.yaml file using Go template expressions, enabling dynamic values based on stack, component, or workflow data. This guide explains how to configure and use this feature.

Subcommands​

Supported List Commands​

CommandDescription
atmos list stacksLists all defined stacks in your project. A stack is a named configuration representing a deployment environment (e.g., dev/us-east-1, prod/eu-west-1).
atmos list componentsLists all available components (Terraform, Helmfile, etc.) defined in the project. Components are reusable infrastructure building blocks.
atmos list workflowsLists all defined workflows, which are custom command sequences defined in atmos.yaml to streamline repetitive tasks.
atmos list valuesDisplays the fully resolved configuration values for a specified component in a stack, after inheritance and imports are applied.
atmos list varsLists the Terraform vars (input variables) that will be passed to a component for a given stack. Useful for debugging variable resolution.
atmos list settingsShows the settings block, typically used for configuring a component’s behavior (e.g., module version, backend type).
atmos list metadataDisplays the metadata block associated with a component in a stack, including attributes like stage, tenant, environment, and namespace.

You can define custom columns for each of these commands individually in your atmos.yaml.

How Column Customization Works​

To customize columns for a specific list command, navigate to the relevant section (e.g., stacks, components, workflows) in your atmos.yaml configuration file. Within that section, define a list block.

Inside the list block:

  1. Specify the output format (optional, defaults to table). Other options include json, yaml, csv, tsv.
  2. Define a columns array. Each element in this array represents a column in the output table and must have:
    • name: The string that will appear as the column header.
    • value: A Go template string that dynamically determines the value for each row in that column.

Example Structure:

# In atmos.yaml
stacks: # Or components, workflows, etc.
  list:
    format: table # Optional
    columns:
      - name: "Header 1"
        value: "{{ .some_template_variable }}"
      - name: "Header 2"
        value: "Static Text or {{ .another_variable }}"
      # ... more columns

YAML Template Syntax​

The value field in each column definition supports Go templates. The available variables within the template depend on the specific atmos list command being customized:

For atmos list stacks:​

{{ .stack_name }}  # Name of the stack
{{ .stack_path }}  # Filesystem path to the stack configuration file

For atmos list components:​

{{ .component_name }}  # Name of the component
{{ .component_type }}  # Type of the component (e.g., terraform, helmfile)
{{ .component_path }}  # Filesystem path to the component directory

For atmos list workflows:​

{{ .name }}      # The name of the workflow
{{ .file }}      # The manifest name
{{ .description }}  # The description provided for the workflow

For atmos list values, atmos list vars, atmos list settings, and atmos list metadata:​

{{ .stack_name }}  # Name of the stack context
{{ .key }}         # The key or property name being listed
{{ .value }}       # The corresponding value for the key

Full Reference: atmos.yaml Structure​

Here's the general structure for defining custom list columns in atmos.yaml:

<command_scope>: # e.g., stacks, components, workflows, values, vars, settings, metadata
  list:
    format: table|json|csv|yaml|tsv  # Optional, default is 'table'
    columns:
      - name: "<Your Column Header>"
        value: "<Go template string using available variables>"
      # ... add more column definitions as needed
  • Replace <command_scope> with the specific scope corresponding to the atmos list command you want to customize (e.g., stacks for atmos list stacks).
  • The columns array is mandatory if you want to override the default columns. If columns is omitted, the command uses its default output columns.

Custom Columns for Workflows​

# In atmos.yaml
workflows:
  list:
    columns:
      - name: Workflow
        value: "{{ .name }}"  # Corresponds to the workflow key in the manifest
      - name: Manifest Name
        value: "{{ .file }}"   # Corresponds to the 'name' field within the manifest file
      - name: Description
        value: "{{ .description }}" # Corresponds to the 'description' field for the workflow
info

Note that {{ .file }} in this context refers to the value of the top-level name attribute within the workflow manifest file itself, not the path to the file.

Display Behavior​

TTY vs Non-TTY Output​

The appearance of the output table depends on whether atmos detects an interactive terminal (TTY) or not:

  • TTY Output (e.g., running in your terminal)

    • Displays a formatted table with borders and styling.
    • Attempts to fit within the terminal width.
    • Uses standard padding between columns (TableColumnPadding = 3).
    • Defaults to format: table if not specified.

  • Non-TTY Output (e.g., redirecting to a file, piping to another command)

    • Produces a simpler, machine-readable format suitable for scripting or automation.
    • Ensures consistent structure for programmatic parsing.

Authentication​

All atmos list subcommands support authentication via the --identity flag or ATMOS_IDENTITY environment variable. This is useful when stack configurations use YAML template functions (e.g., !terraform.state, !terraform.output) that require cloud provider credentials.

Using the --identity Flag​

# Use a specific identity
atmos list stacks --identity my-aws-identity
atmos list components -s tenant1-ue2-dev -i my-aws-identity

# Disable authentication explicitly (use AWS SDK defaults)
atmos list instances --identity=false

Using Environment Variables​

# Set identity via environment variable
ATMOS_IDENTITY=my-aws-identity atmos list stacks

# Using the environment variable with a different command
ATMOS_IDENTITY=my-aws-identity atmos list components

Stack-Level Default Identity​

When neither the --identity flag nor environment variable is set, Atmos automatically loads your stack configuration files to find a default identity configured with default: true:

# In stacks/orgs/acme/_defaults.yaml
auth:
  identities:
    my-default-identity:
      default: true  # This identity will be used automatically

For more details on authentication, refer to Authentication.

Global Flags​

All atmos list subcommands support these flags inherited from the parent command:

--identity / -i (optional)
Authenticate with a specific identity before executing the command.
This is required when YAML template functions need to access remote resources requiring authentication.
atmos list stacks --identity my-aws-identity

Troubleshooting & Tips​

  • Blank Columns: If a column appears empty, double-check the template variable name ({{ .variable }}) against the YAML Template Syntax section for the specific command. Ensure the data context actually contains that variable for the items being listed.
  • Inspecting Available Data: Use the describe command with --format json or --format yaml (e.g., atmos describe stacks --format json) to see the raw data structure and available fields you can use in your templates.
  • Wide Tables: If the table is too wide for your terminal or you encounter errors about content width:
    • Reduce the number of columns defined in your atmos.yaml.
    • Use a different output format like json or yaml.
    • Some list commands might support a --max-columns flag (check command help).
  • Filtering: Use command-specific flags like --stacks 'pattern' for atmos list stacks to filter the rows, which can indirectly simplify the output. Query flags (--query) might also help narrow down data.