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

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`
  , 
  `tree`
  . 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`
- **`--identity` / `-i` (optional)**
  Authenticate with a specific identity before listing components.
  This is required when stack configurations use YAML template functions
  (e.g., 
  `!terraform.state`
  , 
  `!terraform.output`
  ) that require authentication.
  `atmos list components --identity my-aws-identity`
  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`

## 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 }}"
```

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