# 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`](/cli/commands/describe/dependents).

## Usage

Execute the `list dependencies` command like this:

```shell
atmos list dependencies
```

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

```shell
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):

```shell
atmos list dependencies
```

Limit to a single stack:

```shell
atmos list dependencies --stack plat-ue2-dev
```

Focus on a single component:

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

Show only one direction:

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

```shell
# 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.

```text
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.

Optional edges are marked with `[optional]` in tree output. JSON and YAML output
include `optional: true` on the corresponding dependency or dependent entry.

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:

```text
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 within one occurrence, and/or repeated for more, matches all): 
  `--labels=cost-center=platform,compliance:sox`
   or 
  `--labels cost-center=platform --labels 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

- [`atmos describe dependents`](/cli/commands/describe/dependents) - Show the components that depend on a given component
- [`atmos list components`](/cli/commands/list/components) - List all components
- [`atmos list stacks`](/cli/commands/list/stacks) - List all stacks, optionally as a tree with import provenance