Introspection & Querying: describe/list commands, config filtering, workspace introspection, dependency graphs, YQ integration
Atmos provides powerful introspection commands (describe and list) for querying the stack graph,
component configurations, dependencies, and change impact. AI agents operating in a terminal should
use these commands to understand the user's workspace instead of guessing at configurations.
atmos describe component to see the current resolved configatmos describe dependents to see what depends on a componentatmos list stacks and atmos list componentsatmos describe affected or atmos list affected to detect changed stacks--provenance to trace where values originateDisplay the complete, fully resolved configuration for a specific component in a stack.
atmos describe component vpc -s plat-ue2-prod
atmos describe component vpc -s plat-ue2-prod --format json
atmos describe component vpc -s plat-ue2-prod --provenance
atmos describe component vpc -s plat-ue2-prod -q '.vars.cidr_block'
Key flags:
-s, --stack (required) -- Stack name-f, --format -- Output format (yaml, json). Default: yaml--provenance -- Show where each configuration value originated (file:line:column)-q, --query -- Filter output with yq expressions--process-templates / --process-functions -- Enable/disable template and YAML function processing--skip -- Skip specific YAML functions during processingThe output includes all resolved sections: vars, settings, env, backend, metadata,
deps, inheritance, and remote_state_backend.
Show fully deep-merged configuration for all stacks and their components.
atmos describe stacks
atmos describe stacks -s plat-ue2-prod
atmos describe stacks --components vpc,eks
atmos describe stacks --component-types terraform
atmos describe stacks --sections vars,settings
atmos describe stacks -q '.[] | select(.vars.environment == "prod")'
Key flags:
-s, --stack -- Filter by specific stack--components -- Filter by component names (comma-separated)--component-types -- Filter by type (terraform, helmfile, packer)--sections -- Output specific sections (backend, deps, env, inheritance, metadata, remote_state_backend, settings, vars)--include-empty-stacks -- Include stacks with no componentsIdentify components and stacks affected by Git changes between two refs.
atmos describe affected
atmos describe affected --ref main
atmos describe affected --sha abc123
atmos describe affected --include-dependents
atmos describe affected --format json --file affected.json
Key flags:
--ref -- Git reference to compare (default: refs/remotes/origin/HEAD)--sha -- Git commit SHA (takes precedence over --ref)--repo-path -- Path to pre-cloned target repo (fastest, avoids cloning)--clone-target-ref -- Clone the target reference instead of checking out--include-dependents -- Include components that depend on changed components--include-settings -- Include the settings section for each affected component--include-spacelift-admin-stacks -- Include Spacelift admin stacks of affected stacks--exclude-locked -- Exclude components marked as locked--upload -- Upload results to an HTTP endpoint (for CI/CD integration)--ssh-key -- Path to PEM-encoded private key for SSH cloning--ssh-key-password -- Encryption password for the PEM-encoded private key--process-templates -- Enable/disable Go template processing (default: true)--process-functions -- Enable/disable YAML functions processing (default: true)--skip -- Skip executing specific YAML functionsList components that depend on a given component.
atmos describe dependents vpc --stack plat-ue2-prod
atmos describe dependents vpc --stack plat-ue2-prod --format json
Key flags:
--stack (required) -- Stack name-f, --format -- Output format (json, yaml). Default: jsonDisplay the final merged CLI configuration (atmos.yaml resolution result).
atmos describe config
atmos describe config --format json
atmos describe config -q '.stacks.name_pattern'
List all workflows and their associated files.
atmos describe workflows
atmos describe workflows --format json
atmos describe workflows --output map
Display locals defined in stack manifests.
atmos describe locals --stack plat-ue2-prod
atmos describe locals vpc --stack plat-ue2-prod
List all stacks with optional component filtering.
atmos list stacks
atmos list stacks --component vpc
atmos list stacks --format tree --provenance
atmos list stacks --format json
Key flags:
--component -- Filter stacks that contain a specific component--provenance -- Show import provenance (tree format only)-f, --format -- Output format (table, json, yaml, csv, tsv, tree)List all unique component definitions.
atmos list components
atmos list components -s 'plat-*-prod'
atmos list components --type abstract
atmos list components --enabled true
atmos list components --format tree
Key flags:
-s, --stack -- Filter by stack pattern (glob supported)--type -- Filter by component type (real, abstract, all). Default: real--abstract -- Include abstract components--enabled -- Filter by enabled status (true/false)--locked -- Filter by locked status (true/false)List all component-stack combinations (instances).
atmos list instances
atmos list instances --stack 'plat-*-prod'
atmos list instances --format json
atmos list instances --columns component,stack,type
atmos list instances --sort 'stack:asc,component:asc'
Key flags:
--stack -- Filter by stack pattern--filter -- YQ-based filter expressions--columns -- Custom column selection--sort -- Sort specification (e.g., component:asc,stack:desc)--upload -- Upload instances to Atmos Pro APIList affected components in table format (tabular version of describe affected).
atmos list affected
atmos list affected --ref main --include-dependents
atmos list affected --format csv
This is an experimental command.
List all workflows with file and description information.
atmos list workflows
atmos list workflows --file deploy.yaml
atmos list values <component> # Component values across stacks
atmos list vars <component> # Component variables across stacks
atmos list settings <component> # Component settings across stacks
atmos list sources <component> # Component source information
atmos list vendor # Vendor configurations
atmos list aliases # Command aliases
atmos list themes # Available CLI themes
atmos list metadata # Metadata information
| Command Type | Formats |
|---|---|
| Describe commands | yaml, json |
| List commands | table (default), json, yaml, csv, tsv, tree |
# Simple field names
atmos list instances --columns component,stack,type
# Named columns with templates
atmos list instances --columns "Component={{ .component }},Stack={{ .stack }}"
atmos list instances --sort component:asc
atmos list instances --sort "stack:asc,component:desc"
All commands support -q, --query for filtering with yq expressions:
atmos describe stacks -q '.[] | select(.vars.environment == "prod")'
atmos describe component vpc -s plat-ue2-prod -q '.vars'
atmos list instances --filter '.type == "terraform"'
Use --provenance to trace where configuration values originate:
atmos describe component vpc -s plat-ue2-prod --provenance
atmos list stacks --format tree --provenance
Shows file:line:column details and import hierarchy visualization.
# Disable Go template processing
atmos describe component vpc -s prod --process-templates=false
# Disable YAML functions
atmos describe stacks --process-functions=false
# Skip specific YAML functions
atmos describe component vpc -s prod --skip '!terraform.output'
# Use specific identity for YAML function resolution
atmos describe component vpc -s prod -i prod-admin
# Interactive identity selection
atmos describe component vpc -s prod -i
When assisting a user with Atmos configuration, follow this sequence:
atmos describe config to see atmos.yaml settingsatmos list stacks and atmos list componentsatmos describe component <name> -s <stack>atmos describe dependents <name> -s <stack>--provenance to any describe commandatmos describe affected to see impact of modificationsNever guess at stack names, component names, or configuration values. Always query first.