# atmos describe dependents

Use this command to show a list of Atmos components in Atmos stacks that depend on the provided Atmos component.

## Description

Declare component relationships with [`dependencies.components`](/stacks/dependencies/components). The command reads that graph to list the components that depend on the requested component.

Use `name` for the dependency instance, `stack` when it is provisioned in another stack, and `kind` for a cross-type dependency. Use the sibling `dependencies.files` and `dependencies.folders` lists for external paths.

```yaml title="stacks/catalog/terraform/top-level-component1.yaml"
components:
  terraform:
    top-level-component1:
      dependencies:
        components:
          # Same stack
          - name: test/test-component-override
          # Explicit cross-stack dependency
          - name: test/test-component
            stack: tenant1-ue2-dev
          - name: my-component
            stack: tenant1-ue2-staging
        files:
          - tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf
        folders:
          - tests/fixtures/scenarios/complete/components/helmfile/infra/infra-server
      vars:
        enabled: true
```

In this configuration, `top-level-component1` depends on components in the current and named stacks, and is affected when either external path changes.

```yaml title="stacks/catalog/terraform/top-level-component2.yaml"
components:
  terraform:
    top-level-component2:
      metadata:
        component: "top-level-component1"
      dependencies:
        components:
          - name: test/test-component
          - name: test/test2/test-component-2
      vars:
        enabled: true
```

Having the `top-level-component` and `top-level-component2` components configured as shown above, we can now execute the following Atmos command
to show all the components that depend on the `test/test-component` component in the `tenant1-ue2-dev` stack:

```shell
[
    {
        "component": "top-level-component1",
        "component_type": "terraform",
        "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
        "namespace": "cp",
        "tenant": "tenant1",
        "environment": "ue2",
        "stage": "dev",
        "stack": "tenant1-ue2-dev",
        "stack_slug": "tenant1-ue2-dev-top-level-component1",
        "spacelift_stack": "tenant1-ue2-dev-top-level-component1",
        "atlantis_project": "tenant1-ue2-dev-top-level-component1"
    }
]
```

Similarly, the following Atmos command shows all the components that depend on the `test/test-component` component in
the `tenant1-ue2-test-1` stack:

```shell
[
    {
        "component": "top-level-component1",
        "component_type": "terraform",
        "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
        "namespace": "cp",
        "tenant": "tenant1",
        "environment": "ue2",
        "stage": "test-1",
        "stack": "tenant1-ue2-test-1",
        "stack_slug": "tenant1-ue2-dev-top-level-component1",
        "spacelift_stack": "tenant1-ue2-test-1-top-level-component1",
        "atlantis_project": "tenant1-ue2-test-1-top-level-component1"
    },
    {
        "component": "top-level-component2",
        "component_type": "terraform",
        "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
        "namespace": "cp",
        "tenant": "tenant1",
        "environment": "ue2",
        "stage": "test-1",
        "stack": "tenant1-ue2-test-1",
        "stack_slug": "tenant1-ue2-test-1-top-level-component2",
        "atlantis_project": "tenant1-ue2-test-1-top-level-component2"
    }
]
```

After the `test/test-component` has been provisioned, you can use the outputs to perform the following actions:

- Provision the dependent components by executing the Atmos commands `atmos terraform apply top-level-component1 -s tenant1-ue2-test-1` and
  `atmos terraform apply top-level-component2 -s tenant1-ue2-test-1` (on the command line or from a GitHub Action)

- Trigger the dependent Atlantis project

## Usage

```shell
atmos describe dependents [options]
```

:::info YAML Functions and Authentication
By default, `atmos describe dependents` executes YAML template functions (e.g., `!terraform.state`, `!terraform.output`) and Go templates during stack processing. When these functions access remote resources requiring authentication, use the `--identity` flag to authenticate before execution. You can disable function/template processing with `--process-functions=false` or `--process-templates=false` flags.
:::

:::tip
Run `atmos describe dependents --help` to see all the available options
:::

## Examples

```shell
atmos describe dependents test/test-component -s tenant1-ue2-test-1
atmos describe dependents test/test-component -s tenant1-ue2-dev --format yaml
atmos describe dependents test/test-component -s tenant1-ue2-test-1 -f yaml
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --file dependents.json
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --format yaml --file dependents.yaml
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --query <yq-expression>
# Authenticate before describing (when YAML functions require credentials)
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --identity my-aws-identity
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --identity # Interactive selection
# Disable authentication (use AWS SDK defaults)
atmos describe dependents test/test-component -s tenant1-ue2-test-1 --identity=false
atmos describe dependents test/test-component -s tenant1-ue2-test-1 -i my-aws-identity
```

## Arguments

- **`component` (required)**

  Atmos component.

## Flags

- **`--stack` (alias `-s`)(required)**

  Atmos stack.
- **`--format` (alias `-f`)(optional)**

  Output format: `json` or `yaml` (`json` is default).
- **`--file` (optional)**

  If specified, write the result to the file.
- **`--query` (alias `-q`)(optional)**

  Query the results of the command using YQ expressions.

  `atmos describe dependents <component> -s <stack> --query <yq-expression>`.

  For more details, refer to https://mikefarah.gitbook.io/yq.
- **`--process-templates` (optional)**

  Enable/disable processing of `Go` templates in Atmos stacks manifests when executing the command.
  If the flag is not provided, it's set to `true` by default.

  `atmos describe dependents <component> -s <stack> --process-templates=false`
- **`--process-functions` (optional)**

  Enable/disable processing of Atmos YAML functions in Atmos stacks manifests when executing the command.
  If the flag is not provided, it's set to `true` by default.

  `atmos describe dependents <component> -s <stack> --process-functions=false`
- **`--skip` (optional)**

  Skip processing a specific Atmos YAML function in Atmos stacks manifests when executing the command.
  To specify more than one function, use multiple `--skip` flags, or separate the functions with a comma:

  `atmos describe dependents <component> -s <stack> --skip=terraform.output --skip=include`

  `atmos describe dependents <component> -s <stack> --skip=terraform.output,include`
- **`--identity` / `-i` (optional)**

  Authenticate with a specific identity before describing dependents.
  This is required when YAML template functions (e.g., `!terraform.state`, `!terraform.output`)
  need to access remote resources requiring authentication.
  Use without a value for interactive identity selection:

  `atmos describe dependents <component> -s <stack> --identity` (interactive)

  `atmos describe dependents <component> -s <stack> --identity my-aws-identity` (specific identity)

  For more details, refer to [Authentication](/cli/commands/auth/usage).

## Output

The command outputs a list of objects (in JSON or YAML format).

Each object has the following schema:

```json
{
  "component": "....",
  "component_type": "....",
  "component_path": "....",
  "namespace": "....",
  "tenant": "....",
  "environment": "....",
  "stage": "....",
  "stack": "....",
  "stack_slug": "",
  "spacelift_stack": ".....",
  "atlantis_project": "....."
}
```

where:

- `component` - the dependent Atmos component

- `component_type` - the type of the dependent component (`terraform` or `helmfile`)

- `component_path` - the filesystem path to the `terraform` or `helmfile` component

- `namespace` - the `namespace` where the dependent Atmos component is provisioned

- `tenant` - the `tenant` where the dependent Atmos component is provisioned

- `environment` - the `environment` where the dependent Atmos component is provisioned

- `stage` - the `stage` where the dependent Atmos component is provisioned

- `stack` - the Atmos stack where the dependent Atmos component is provisioned

- `stack_slug` - the Atmos stack slug (concatenation of the Atmos stack and Atmos component)

- `spacelift_stack` - the dependent Spacelift stack. It will be included only if the Spacelift workspace is enabled for the dependent Atmos component
  in the Atmos stack in the `settings.spacelift.workspace_enabled` section (either directly in the component's `settings.spacelift.workspace_enabled`
  section or via inheritance)

- `atlantis_project` - the dependent Atlantis project name. It will be included only if the Atlantis integration is configured in
  the `settings.atlantis` section in the stack manifest. Refer to [Atlantis Integration](/cli/configuration/integrations/atlantis) for more details.

:::note

Abstract Atmos components (`metadata.type` is set to `abstract`) are not included in the output since they serve as blueprints for other
Atmos components and are not meant to be provisioned.

Disabled components (`metadata.enabled: false`) are also excluded from dependents.
:::

## Output Example

```shell
[
{
    "component": "top-level-component2",
    "component_type": "terraform",
    "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
    "namespace": "cp",
    "tenant": "tenant1",
    "environment": "ue2",
    "stage": "test-1",
    "stack": "tenant1-ue2-test-1",
    "stack_slug": "tenant1-ue2-dev-top-level-component2",
    "atlantis_project": "tenant1-ue2-test-1-top-level-component2"
},
{
    "component": "top-level-component1",
    "component_type": "terraform",
    "component_path": "tests/fixtures/scenarios/complete/components/terraform/top-level-component1",
    "namespace": "cp",
    "tenant": "tenant1",
    "environment": "ue2",
    "stage": "dev",
    "stack": "tenant1-ue2-dev",
    "stack_slug": "tenant1-ue2-test-1-top-level-component1",
    "spacelift_stack": "tenant1-ue2-dev-top-level-component1",
    "atlantis_project": "tenant1-ue2-dev-top-level-component1"
}
]
```