# 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.

> **Key points**
>
> - 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

**File:** `atmos.yaml`

```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](#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`:

**File:** `atmos.yaml`

```yaml
list:
  components:
    format: table
  instances:
    format: json
```

### Custom Columns with Conditional Logic

Use template functions to derive columns:

**File:** `atmos.yaml`

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

- [`atmos list components`](/cli/commands/list/components) — List unique components
- [`atmos list instances`](/cli/commands/list/list-instances) — List component instances
- [`atmos list stacks`](/cli/commands/list/stacks) — List stacks
- [Settings](/cli/configuration/settings) — Other top-level settings