# atmos list components

Use this command to list all components in your Atmos configuration, optionally filtering by stack. View components in multiple output formats including tables, JSON, YAML, and CSV.

_\[Video: atmos list components]_

## Usage

Execute the `list components` command like this:

```shell
atmos list components
```

This command lists Atmos components in all stacks or in a specified stack:

```shell
atmos list components -s <stack>
```

:::tip
Run `atmos list components --help` to see all the available options
:::

## Examples

```shell
atmos list components
atmos list components -s tenant1-ue2-dev
```

Filter by component type:

```shell
# List only real (non-abstract) components
atmos list components --type real

# List abstract components
atmos list components --type abstract

# List all components including abstract
atmos list components --type all
```

Filter by enabled/locked status:

```shell
# List only enabled components
atmos list components --enabled=true

# List only locked components
atmos list components --locked=true
```

Filter by tags and labels:

```shell
# List components tagged production or tier-1 (matches any)
atmos list components --tags production,tier-1

# List components labeled cost-center=platform (matches all given labels)
atmos list components --labels cost-center=platform

# Combine multiple selectors in one comma-separated --labels value
atmos list components --labels cost-center=platform,compliance=sox

# Combine tags and labels
atmos list components --tags production,tier-1 --labels cost-center=platform
```

Include abstract components:

```shell
# Include abstract components (normally hidden by default)
atmos list components --abstract

# Equivalent: show all component types
atmos list components --type all
```

Output in different formats:

```shell
# JSON format
atmos list components --format json

# YAML format
atmos list components --format yaml

# CSV format with custom delimiter
atmos list components --format csv
```

Custom columns:

```shell
# Simple field names (auto-generates templates)
atmos list components --columns component,stack,type

# Named columns with custom templates
atmos list components --columns "Name={{ .component }},Stack={{ .stack }}"

# Named columns with simple field reference
atmos list components --columns "MyStack=stack,MyType=type"

# Mix of formats
atmos list components --columns component,"Status={{ if .enabled }}Active{{ else }}Disabled{{ end }}"
```

Sort results:

```shell
# Sort by component name ascending
atmos list components --sort component:asc

# Sort by multiple columns
atmos list components --sort "stack:asc,component:desc"
```

Query with YQ expressions:

```shell
# Simplified syntax - just use select() directly
atmos list components --query 'select(.locked == true)'

# Filter to only terraform components
atmos list components --query 'select(.kind == "terraform")'

# Get components in prod stacks
atmos list components --query 'select(.stack | test("prod"))'

# Get components by name
atmos list components --query 'select(.component == "vpc")'

# Output query results as JSON
atmos list components --query 'select(.kind == "terraform")' --format json

# You can also use the verbose syntax if preferred
atmos list components --query '[.[] | select(.locked == true)]'
```

:::tip Simplified Query Syntax
Atmos automatically normalizes YQ queries for convenience:

- `select(.locked == true)` → automatically becomes `[.[] | select(.locked == true)]`
- `.[] | select(...)` → automatically wrapped in `[...]` to prevent YAML parsing issues

This means you can write simple `select()` expressions without worrying about the verbose syntax.

**Note:** Scalar extraction queries like `.[].component` are not supported. Use `atmos describe component --query` for field extraction, or use `select(...)` to filter components.
:::

## Flags

- **`--stack` / `-s`** — Filter by stack name pattern (supports glob patterns like `plat-*-prod`).Environment variable: `ATMOS_STACK`
- **`--format` / `-f`** — Output format: `table`, `json`, `yaml`, `csv`, `tsv`. Overrides `components.list.format` configuration in atmos.yaml (default: `table`).Environment variable: `ATMOS_LIST_FORMAT`
- **`--columns`** — Columns to display. Supports simple field names (e.g., `component,stack,type`), named columns with templates (e.g., `"Name={{ .component }}"`), or named with field reference (e.g., `"MyStack=stack"`). Overrides `components.list.columns` configuration in atmos.yaml. Environment variable: `ATMOS_LIST_COLUMNS`
- **`--type` / `-t`** — Component type: `real`, `abstract`, `all` (default: `real`).Environment variable: `ATMOS_COMPONENT_TYPE`
- **`--abstract`** — Include abstract components in output. Equivalent to `--type all`.Environment variable: `ATMOS_ABSTRACT`
- **`--enabled`** — Filter by enabled status (omit for all, `--enabled=true` for enabled only, `--enabled=false` for disabled only). Because `list components` returns each component deduplicated across stacks, a component is reported as `enabled=false` if it is disabled in **any** of its stack instances. To see per-stack-instance state, use [`atmos list instances`](/cli/commands/list/list-instances).Environment variable: `ATMOS_COMPONENT_ENABLED`
- **`--locked`** — Filter by locked status (omit for all, `--locked=true` for locked only, `--locked=false` for unlocked only). A deduplicated component is reported as `locked=true` if it is locked in **any** of its stack instances. Use [`atmos list instances`](/cli/commands/list/list-instances) for per-stack-instance state.Environment variable: `ATMOS_COMPONENT_LOCKED`
- **`--sort`** — Sort by column:order (e.g., `component:asc,stack:desc`). Multiple sort columns separated by comma.Environment variable: `ATMOS_LIST_SORT`
- **`--query` / `-q`** — Filter results using YQ expressions. Supports simplified syntax like `select(.locked == true)` which is automatically normalized. See the [YQ documentation](https://mikefarah.gitbook.io/yq) for expression syntax.Environment variable: `ATMOS_LIST_QUERY`
- **`--tags`** — Filter by tags (comma-separated, matches any): `--tags=production,tier-1`. Components are tagged via an optional `metadata.tags: [...]` list in stack manifests.Environment variable: `ATMOS_COMPONENT_TAGS`
- **`--labels`** — Filter by labels (comma-separated `key=value` or `key:value` pairs in one flag value, matches all): `--labels=cost-center=platform,compliance:sox`. Components are labeled via an optional `metadata.labels: {...}` map in stack manifests.Environment variable: `ATMOS_COMPONENT_LABELS`
- **`--include-dependencies`** — Expand the listing to everything the selected components depend on (their prerequisites) — previewing the exact set a terraform bulk command with the same selection flags would execute. The closure covers Terraform components (the dependency graph the scheduler executes) and is evaluated with this command's own `--process-templates`/`--process-functions` settings. Accepts an optional depth (for example, `--include-dependencies=1` for direct dependencies only).`atmos list components --labels=env=dev --include-dependencies`Environment variable: `ATMOS_INCLUDE_DEPENDENCIES`
- **`--include-dependents`** — Expand the listing to everything that depends on the selected components — previewing the exact set a terraform bulk command with the same selection flags would execute. Accepts an optional depth (for example, `--include-dependents=2` for two levels).Environment variable: `ATMOS_INCLUDE_DEPENDENTS`
- **`--identity` / `-i` (optional)** — Explicitly authenticate before listing components; failures remain fatal. Without explicit selection, default identity authentication occurs only when an evaluated value needs credentials. Unused column values do not trigger authentication. Use `--identity=false` to disable Atmos authentication.Environment variable: `ATMOS_IDENTITY`
- **`--process-templates`** — Enable/disable Go template processing in Atmos stack manifests (default `true`). Go template functions include `atmos.Component(...)`.Environment variable: `ATMOS_PROCESS_TEMPLATES`
- **`--process-functions`** — Enable/disable YAML functions processing in Atmos stack manifests (default `true`). YAML functions include `!terraform.state`, `!terraform.output`, `!store`, `!aws.*`, etc. This is distinct from Go template functions like `atmos.Component(...)`, which are controlled by `--process-templates`.Environment variable: `ATMOS_PROCESS_FUNCTIONS`
- **`--skip`** — Skip executing a specific YAML function in the Atmos stack manifests when processing stacks. Repeat the flag to skip multiple functions (for example, `--skip terraform.state --skip terraform.output`). Use this to bypass a single function (such as a backend-resolving `!terraform.state` call) while leaving other YAML functions enabled.Environment variable: `ATMOS_SKIP`
- **`--error-mode`** — How to handle unavailable requested values, including missing Terraform state and unavailable implicit authentication (default `warn`). `warn` substitutes `(computed)` and prints one summary; `silent` omits the summary; `strict` fails. Explicit identity failures, malformed configuration, invalid expressions, and dependency cycles remain fatal.Environment variable: `ATMOS_LIST_ERROR_MODE`

## Configuration

You can customize the default output format and columns displayed by `atmos list components` in your `atmos.yaml`:

### Default Format

```yaml
# atmos.yaml
components:
  list:
    format: yaml  # Default format: table, json, yaml, csv, tsv
```

**Precedence**: CLI `--format` flag > Config file > Environment variable `ATMOS_LIST_FORMAT` > Default (`table`)

### Custom Columns

```yaml
# atmos.yaml
components:
  list:
    format: table
    columns:
      - name: Component
        value: "{{ .component }}"
      - name: Stack
        value: "{{ .stack }}"
      - name: Kind
        value: "{{ .kind }}"
      - name: Type
        value: "{{ .type }}"
      - name: Description
        value: "{{ .metadata.description }}"
```

### Available Template Fields

Column `value` fields support Go template syntax with access to:

- **`.component`** — Component name
- **`.stack`** — Stack name
- **`.kind`** — Component runner type (`terraform`, `helmfile`, `packer`)
- **`.type`** — Component type from metadata (`real` or `abstract`)
- **`.component_path`** — Filesystem path to the component source directory
- **`.status`** — Colored status indicator (● green=enabled, red=locked, gray=disabled)
- **`.status_text`** — Status as text (`enabled`, `disabled`, `locked`)
- **`.enabled`** — Whether component is enabled (boolean)
- **`.locked`** — Whether component is locked (boolean)
- **`.vars`** — All component variables (e.g., `.vars.region`, `.vars.tenant`)
- **`.settings`** — Component settings
- **`.metadata`** — Full metadata map (e.g., `.metadata.description`, `.metadata.component`)
- **`.data`** — Full component data for advanced templates

### Template Functions

Columns support template functions for data transformation:

```yaml
components:
  list:
    columns:
      - name: Component (Upper)
        value: "{{ .component | upper }}"
      - name: Region
        value: "{{ .vars.region | default \"N/A\" }}"
      - name: Status
        value: "{{ if .enabled }}Enabled{{ else }}Disabled{{ end }}"
      - name: Short Description
        value: "{{ .metadata.description | truncate 50 }}"
```

Available functions:

- `upper`, `lower` - String case conversion
- `truncate` - Truncate string with ellipsis
- `len` - Length of arrays/strings
- `default` - Provide default value if empty
- `toString` - Convert value to string
- `ternary` - Conditional expression

### Override Columns via CLI

Override configured columns using the `--columns` flag. The flag supports multiple formats:

**Simple field names** (auto-generates templates and title-case names):

```shell
# Display component, stack, and type columns
atmos list components --columns component,stack,type

# Include enabled status
atmos list components --columns component,stack,enabled
```

**Named columns with templates** (full control over display name and value):

```shell
# Custom column names with templates
atmos list components --columns "Name={{ .component }},Stack={{ .stack }}"

# Complex templates with conditionals
atmos list components --columns "Status={{ if .enabled }}Active{{ else }}Disabled{{ end }}"
```

**Named columns with field reference** (auto-wraps field in template):

```shell
# Shorthand: Name=field becomes Name={{ .field }}
atmos list components --columns "MyComponent=component,MyStack=stack"
```

**Mixed formats**:

```shell
# Combine simple fields and named columns
atmos list components --columns component,"CustomType={{ .type | upper }}"
```

## Try it out

### demo-stacks

Copy the example into a new directory and make it your own:

```shell
atmos init examples/demo-stacks
cd demo-stacks
```

List the components in the example.

```shell
atmos list components
```

- [Installation guide](/install)
- [Explore the example](/examples/demo-stacks)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)

## Related Commands

- [`atmos list instances`](/cli/commands/list/list-instances) - List all component instances across stacks
- [`atmos list stacks`](/cli/commands/list/stacks) - List all stacks
- [`atmos describe component`](/cli/commands/describe/component) - Get detailed component configuration