Skip to main content

List Command Configuration

The top-level list: section in atmos.yaml configures the default output of the atmos list family of commands. You can pin the output format, customize which columns appear, control column widths, and use Go templates to derive column values from component, stack, and variable data — without passing --columns or --format flags every time.

You will learn

  • Set per-command defaults for list components, list instances, and list stacks
  • Control output format (table, json, csv)
  • Define columns with Go templates that read component/stack/var data
  • CLI flags (--columns, --format) still override config defaults

Configuration​

atmos.yaml

list:
  # Defaults for `atmos list components`.
  components:
    format: table
    columns:
      - name: Component
        value: "{{ .component }}"
      - name: Type
        value: "{{ .type }}"
      - name: Stacks
        value: "{{ .stack_count }}"

  # Defaults for `atmos list instances`.
  instances:
    format: table
    columns:
      - name: Stack
        value: "{{ .stack }}"
      - name: Component
        value: "{{ .component }}"
      - name: Tenant
        value: "{{ .vars.tenant }}"
      - name: Environment
        value: "{{ .vars.environment }}"
      - name: Stage
        value: "{{ .vars.stage }}"

  # Defaults for `atmos list stacks`.
  stacks:
    format: table
    columns:
      - name: Stack
        value: "{{ .stack }}"

Configuration Reference​

list.components

Default output configuration for atmos list components. This command lists unique component definitions, deduplicated across stacks.

list.instances

Default output configuration for atmos list instances. This command lists one row per component+stack pair (every materialized instance).

list.stacks

Default output configuration for atmos list stacks.

Each section accepts the same fields:

format

Output format when no --format flag is supplied. One of table, json, or csv. If empty, defaults to table.

  • Type: string
  • Allowed values: table, json, csv
  • Default: table
columns

Ordered list of columns to render. Each entry is an object with:

name
The column header that appears in table output and the field name in CSV/JSON output.
value
A Go template expression evaluated per row. The available context depends on which list command is being run (see Template Context below).
width
Optional fixed column width (in characters) for table output. Omit to let the renderer auto-size.

When columns is empty or omitted, each list command falls back to its built-in default columns.

Template Context​

The value template for each column is rendered against a row context whose keys vary by command.

list components​

Lists unique components — one row per component definition.

{{ .component }}
The component name (e.g., vpc, eks/cluster).
{{ .type }}
The component type (terraform, helmfile, packer, ansible).
{{ .stack_count }}
How many stacks this component appears in.

list instances​

Lists instances — one row per component+stack pair. The full per-instance configuration is available, including:

{{ .component }}, {{ .stack }}
The component name and the stack it's deployed in.
{{ .type }}
The component type (terraform, helmfile, etc.).
{{ .vars.<name> }}
Any variable defined in the stack manifest, e.g., {{ .vars.tenant }}, {{ .vars.environment }}, {{ .vars.stage }}, {{ .vars.region }}.
{{ .settings.<key> }}
Any value under the component's settings: block.
{{ .metadata.<key> }}
Component metadata fields like metadata.type, metadata.locked.

list stacks​

Lists stacks — one row per stack name. Useful fields include {{ .stack }} and any locals or variables resolved at the stack level.

NOTE:

Templates use the same Go template engine as the rest of Atmos. Sprig and Gomplate functions are available, so you can format, default, or compute values inline (e.g., {{ .vars.region | default "us-east-1" }}).

Precedence​

For each list command, output is resolved with the following precedence (highest to lowest):

  1. CLI flags — --format, --columns "Name=template"
  2. list.<command> configuration in atmos.yaml
  3. Built-in defaults

Backward Compatibility​

Earlier versions of Atmos used components.list.columns for the list instances command. That path is still honored as a fallback when list.instances.columns is unset, but new configurations should use the top-level list: section so each command can be configured independently.

Examples​

Per-Format Defaults​

Default to JSON for scripting while keeping the table layout for list components:

atmos.yaml

list:
  components:
    format: table
  instances:
    format: json

Custom Columns with Conditional Logic​

Use template functions to derive columns:

atmos.yaml

list:
  instances:
    columns:
      - name: Stack
        value: "{{ .stack }}"
        width: 30
      - name: Component
        value: "{{ .component }}"
      - name: Region
        value: "{{ .vars.region | default \"us-east-1\" }}"
      - name: Locked
        value: "{{ if .metadata.locked }}🔒{{ else }} {{ end }}"

See Also​