Skip to main content

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.

atmos list metadata --help

Usage​

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.

Examples​

List all component metadata:

atmos list metadata

Filter by stack pattern:

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

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

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

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

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

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

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:

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

> 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 for settings data)