# 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`
  )
- **`--filter`**
  Filter expression using YQ syntax (e.g., 
  `.enabled == true`
  )
- **`--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:

```shell
# Find all enabled components
atmos list metadata --filter '.enabled == true'

# Find all abstract components
atmos list metadata --filter '.type == "abstract"'

# Find locked components
atmos list metadata --filter '.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 `--filter` to find specific metadata patterns (e.g., locked components, abstract components)
- Combine `--stack` (glob) with `--filter` (YQ) for precise filtering
- 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