# atmos list metadata

Use this command to list component metadata across all stacks, displaying custom metadata fields in a table. Filter and sort metadata to quickly find components with specific attributes.

## Usage

```shell
atmos list metadata [flags]
```

## Description

The `atmos list metadata` command displays component metadata across all stacks in a tabular format. Each row represents a component instance, showing metadata fields like:

- Component type (`abstract` or `real`)
- Enabled/disabled status
- Locked status
- Base component name
- Inheritance chain
- Description

This command is useful for:

- Auditing component types across environments
- Finding enabled/disabled components
- Understanding component inheritance patterns
- Verifying locked components

## Flags

- **`--format` / `-f`** — Output format: `table`, `json`, `yaml`, `csv`, `tsv` (default: `table`)
- **`--columns`** — Columns to display (comma-separated). Overrides `components.list.columns` configuration in atmos.yaml
- **`--stack` / `-s`** — Filter by stack pattern (supports glob patterns, e.g., `plat-*-prod`)
- **`--tags`** — Filter by component 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 component 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`
- **`--filter`** — Reserved. The flag is accepted for consistency with other `list` commands, but a YQ filter expression is not yet applied to metadata listings — use `--tags`/`--labels` (or post-process `--format json` output with an external tool) to narrow results.
- **`--sort`** — Sort by column:order (e.g., `stack:asc,component:desc`)
- **`--delimiter`** — Delimiter for csv/tsv output (default: `,` for csv, `\t` for tsv)
- **`--identity` / `-i` (optional)** — Authenticate with a specific identity before listing metadata.This is required when stack configurations use YAML template functions(e.g., `!terraform.state`, `!terraform.output`) that require authentication.`atmos list metadata --identity my-aws-identity`Can also be set via `ATMOS_IDENTITY` environment variable.
- **`--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`

## Examples

List all component metadata:

```shell
atmos list metadata
```

Filter by stack pattern:

```shell
# List metadata for production stacks
atmos list metadata --stack '*-prod'

# List metadata for specific environment
atmos list metadata --stack 'plat-ue2-*'
```

Filter by metadata fields with an external tool (the `--filter` flag is not yet applied to metadata listings):

```shell
# Find all enabled components
atmos list metadata --format json | jq '.[] | select(.enabled == true)'

# Find all abstract components
atmos list metadata --format json | jq '.[] | select(.type == "abstract")'

# Find locked components
atmos list metadata --format json | jq '.[] | select(.locked == true)'
```

Output in different formats:

```shell
# JSON format for machine processing
atmos list metadata --format json

# YAML format for configuration review
atmos list metadata --format yaml

# CSV format for spreadsheet analysis
atmos list metadata --format csv
```

Sort metadata:

```shell
# Sort by stack name ascending
atmos list metadata --sort stack:asc

# Multi-column sort
atmos list metadata --sort "type:desc,stack:asc,component:asc"
```

Custom column selection:

```shell
# Show only essential fields
atmos list metadata --columns stack,component,type,enabled

# Show inheritance information
atmos list metadata --columns "component,component_base,inherits"
```

## Custom Columns Configuration

You can customize the columns displayed by `atmos list metadata` in your `atmos.yaml`:

```yaml
# atmos.yaml
components:
  list:
    columns:
      - name: Stack
        value: "{{ .stack }}"
      - name: Component
        value: "{{ .component }}"
      - name: Type
        value: "{{ .type }}"
      - name: Enabled
        value: "{{ .enabled }}"
      - name: Locked
        value: "{{ .locked }}"
      - name: Base Component
        value: "{{ .component_base }}"
      - name: Inherits
        value: "{{ .inherits }}"
      - name: Description
        value: "{{ .description }}"
```

### Available Template Fields

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

- `.stack` - Stack name
- `.component` - Component name
- `.component_type` - Component type (`terraform`, `helmfile`, etc.)
- `.type` - Metadata type (`abstract`, `real`)
- `.enabled` - Whether component is enabled (boolean)
- `.locked` - Whether component is locked (boolean)
- `.component_base` - Base Terraform/Helmfile component
- `.inherits` - Comma-separated list of inherited components
- `.description` - Component description
- `.metadata` - Full metadata map for advanced templates

### Template Functions

Columns support template functions for data transformation:

```yaml
components:
  list:
    columns:
      - name: Component (Upper)
        value: "{{ .component | upper }}"
      - name: Status
        value: "{{ if .enabled }}✓ Enabled{{ else }}✗ Disabled{{ end }}"
      - name: Type Badge
        value: "{{ if eq .type \"abstract\" }}[A]{{ else }}[R]{{ end }}"
      - name: Has Inherits
        value: "{{ if .inherits }}Yes{{ else }}No{{ end }}"
```

Available functions:

- `upper`, `lower` - String case conversion
- `truncate` - Truncate string with ellipsis
- `len` - Length of arrays/strings
- `toString` - Convert value to string
- `ternary` - Conditional expression
- `eq`, `ne` - Equality comparison

### Override Columns via CLI

Override configured columns using the `--columns` flag:

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

# Display custom subset
atmos list metadata --columns "stack,component,type,enabled,locked"
```

## Example Output

```shell
> atmos list metadata
┌─────────────────┬───────────┬──────────┬─────────┬────────┬────────────────┬──────────────┬────────────────────┐
│     Stack       │ Component │   Type   │ Enabled │ Locked │ Base Component │   Inherits   │    Description     │
├─────────────────┼───────────┼──────────┼─────────┼────────┼────────────────┼──────────────┼────────────────────┤
│ plat-ue2-dev    │ vpc       │ real     │ true    │ false  │ vpc            │ vpc/defaults │ Development VPC    │
│ plat-ue2-dev    │ eks       │ real     │ true    │ false  │ eks            │ eks/defaults │ Development EKS    │
│ plat-ue2-prod   │ vpc       │ real     │ true    │ true   │ vpc            │ vpc/defaults │ Production VPC     │
│ plat-ue2-prod   │ eks       │ real     │ true    │ true   │ eks            │ eks/defaults │ Production EKS     │
└─────────────────┴───────────┴──────────┴─────────┴────────┴────────────────┴──────────────┴────────────────────┘
```

:::tip

- Use `--tags`/`--labels` to narrow by component metadata, and `--stack` (glob) to narrow by stack
- The `--sort` flag supports multi-column sorting for organized output
- Metadata is component-level configuration (use [`atmos list settings`](/cli/commands/list/settings) for settings data)
  :::

## Related Commands

- [`atmos list instances`](/cli/commands/list/list-instances) - List all component instances with full configuration
- [`atmos list components`](/cli/commands/list/components) - List all components
- [`atmos list settings`](/cli/commands/list/settings) - List component settings
- [`atmos describe component`](/cli/commands/describe/component) - Get detailed component configuration