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

Configuration Reference[Read more](/cli/configuration/stacks)

## Usage

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

| 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:**

```yaml
# 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`:

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

### For `atmos list components`:

```yaml
{{ .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`:

```yaml
{{ .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`:

```yaml
{{ .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`:

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

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

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

```shell
# 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`:

```yaml
# 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](/cli/commands/auth/usage).

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