Skip to main content

atmos list dependencies

Use this command to visualize the dependency relationships between Atmos components across stacks. By default it renders a tree showing both directions for every component — what each component depends on, and what depends on it. Dependencies are read from both dependencies.components (preferred) and the legacy settings.depends_on, so the output stays consistent with atmos describe dependents.

atmos list dependencies --help

Usage​

Execute the list dependencies command like this:

atmos list dependencies

Focus on a single component in a stack by passing the component as a positional argument:

atmos list dependencies <component> --stack <stack>
tip

Run atmos list dependencies --help to see all the available options.

Examples​

List dependencies for every component (tree, both directions):

atmos list dependencies

Limit to a single stack:

atmos list dependencies --stack plat-ue2-dev

Focus on a single component:

atmos list dependencies vpc --stack plat-ue2-dev

Show only one direction:

# What the component depends on (its prerequisites)
atmos list dependencies vpc --stack plat-ue2-dev --direction forward

# What depends on the component (its dependents)
atmos list dependencies vpc --stack plat-ue2-dev --direction reverse

Output as structured data:

# JSON
atmos list dependencies --format json

# YAML
atmos list dependencies --format yaml

Tree Output​

The default tree format keeps stack context next to the component dependency tree. The Component column carries the hierarchy, while Type is secondary metadata on the right. Repeated metadata is omitted on child rows unless the stack or type changes.

Dependencies
Stack         Component                 Type
plat-ue2-dev  app-config                terraform
              ├──depends on ↓
              │  ├──▶ dynamodb-table
              │  └──▶ kms-key
              └──required by ↑
                 └──(none)

plat-ue2-dev  kms-key                   terraform
              ├──depends on ↓
              │  └──(none)
              └──required by ↑
                 └──◀ app-config

The filled triangle marker shows edge direction:

  • ▶ marks a forward dependency edge: the selected component depends on that child.
  • ◀ marks a reverse dependency edge: that child depends on the selected component.

When you select a single direction with --direction forward or --direction reverse, the dependency subtree is attached directly under each component (no depends on / required by branch labels).

Circular dependencies are detected and marked with (circular reference) so the tree always terminates instead of recursing forever — unlike the execution dependency graph used by terraform --affected, this command tolerates cycles so they can be inspected.

Levels Output​

The levels format shows each component's shortest dependency-graph distance from the selected root(s). It lists every reachable component ordered by distance:

Level  Stack         Component       Type
0      plat-ue2-dev  app             terraform
1      plat-ue2-dev  database        terraform
1      plat-ue2-dev  vpc             terraform
2      plat-ue2-dev  kms-key         terraform

With --direction forward, each level is a deployment prerequisite distance. --direction reverse follows dependents. With the default --direction both, Level is the shortest path in either direction. Components selected by the positional component argument, --stack, --tags, or --labels start at level 0.

Arguments​

component (optional)
Limit the top-level entries to a single component. Combine with --stack to target one specific component instance.

Flags​

--direction / -d
Dependency direction to show: both (default), forward (what the component depends on), or reverse (what depends on the component).
Environment variable: ATMOS_LIST_DIRECTION
--stack / -s
Filter the top-level entries to a single stack. Cross-stack dependency edges are still resolved and displayed.
Environment variable: ATMOS_STACK
--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. Like --stack, this scopes which components appear as top-level entries; dependency subtrees still traverse the full graph.
Environment variable: ATMOS_COMPONENT_TAGS
--labels
Filter by component labels (comma-separated key=value or key:value pairs, matches all): --labels=cost-center=platform,compliance:sox. Components are labeled via an optional metadata.labels: {...} map in stack manifests. Like --stack, this scopes which components appear as top-level entries; dependency subtrees still traverse the full graph.
Environment variable: ATMOS_COMPONENT_LABELS
--format / -f
Output format: tree (default), json, yaml, or levels.
Environment variable: ATMOS_LIST_DEPENDENCIES_FORMAT
--identity / -i (optional)
Authenticate with a specific identity before listing dependencies.
This is required when stack configurations use YAML template functions
(e.g., !terraform.state, !terraform.output) that require authentication.
Environment variable: ATMOS_IDENTITY
--process-templates
Enable/disable Go template processing in Atmos stack manifests (default true). Templates are processed so that cross-stack dependency references using templated stack names (e.g., stack: "ue1-{{ .vars.stage }}") resolve correctly.
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.
Environment variable: ATMOS_PROCESS_FUNCTIONS
--skip
Skip executing a specific YAML function when processing stacks. Repeat the flag to skip multiple functions (for example, --skip terraform.state --skip terraform.output).
Environment variable: ATMOS_SKIP

Related Commands​