atmos list

Purpose

Use these subcommands to list sections of Atmos configurations.

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

📄️ components

Use this command to list Atmos components

📄️ metadata

The atmos list metadata command displays component metadata across all stacks.

📄️ settings

The atmos list settings command displays component settings across all stacks.

📄️ stacks

Use this command to list all Stack configurations or a stack of a specified component.

📄️ values

The atmos list values command displays component values across all stacks where the component is used.

📄️ vars

The atmos list vars command displays component variables across all stacks where the component is used.

📄️ workflows

The atmos list workflows command displays all Atmos workflows defined in your project.

Supported List Commands

Command	Description
atmos list stacks	Lists 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 components	Lists all available components (Terraform, Helmfile, etc.) defined in the project. Components are reusable infrastructure building blocks.
atmos list workflows	Lists all defined workflows, which are custom command sequences defined in atmos.yaml to streamline repetitive tasks.
atmos list values	Displays the fully resolved configuration values for a specified component in a stack, after inheritance and imports are applied.
atmos list vars	Lists the Terraform vars (input variables) that will be passed to a component for a given stack. Useful for debugging variable resolution.
atmos list settings	Shows the settings block, typically used for configuring a component’s behavior (e.g., module version, backend type).
atmos list metadata	Displays 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.

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.