# atmos.describe

The `atmos.describe` function runs `atmos describe` through the current Atmos executable. Use it to read the
fully merged configuration of stacks and components, find affected components, and inspect dependents from
automation.

## Usage

```python
atmos.describe(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "capture",
    check = True,
)
```

Calls default to JSON and captured output. Read `result.data` directly; `result.stdout`
retains the raw JSON. Explicit formats and `output = "stream"` override these defaults.
Subcommands without a `--format` flag retain their native format. See
[query defaults](/functions/automation/atmos.run#query-defaults).

## Subcommands

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call
`atmos.describe("component", "station", flags = {"stack": "dev"})` runs
`atmos describe component station --stack=dev`.

| Subcommand | Purpose |
| --- | --- |
| [`component`](/cli/commands/describe/component) | Show configuration details for a component in a stack. |
| [`stacks`](/cli/commands/describe/stacks) | Display configuration for stacks and their components. |
| [`affected`](/cli/commands/describe/affected) | List components and stacks affected by two Git commits. |
| [`dependents`](/cli/commands/describe/dependents) | List components that depend on a given component. Also available as `dependants`. |
| [`locals`](/cli/commands/describe/locals) | Display locals from stack manifests. |
| [`workflows`](/cli/commands/describe/workflows) | List workflows and their associated files. |
| [`config`](/cli/commands/describe/config) | Display the final merged CLI configuration. |
| [`edition`](/cli/commands/describe/edition) | Display the active edition pin and the defaults it rolls back. |

See the [`atmos describe` command reference](/cli/commands/describe/usage) for the complete list of subcommands and
flags.

## Arguments

- **`*positionals`**

  (Optional) Strings placed on the command line right after `describe`, in order: the subcommand and its positional arguments, such as the component name for `component` and `dependents`. Every value must be a string.
- **`flags`**

  (Optional) A dictionary of command-line options; see
  [flag translation](/functions/automation/atmos.run#flag-translation). The `stack` key becomes `--stack` for
  the subcommands that take one, `format` selects the output format, and `query` applies a yq expression to
  the result. Other common keys include `process-templates`, `process-functions`, and `skip`. The
  `describe component` subcommand also accepts `provenance`.
- **`args`**
  (Optional) A list or tuple of strings appended after the flags.
- **`working_directory`, `env`, `output`, `check`**

  (Optional) See [`atmos.run`](/functions/automation/atmos.run#arguments) for process options and defaults.

Options other than the positionals are keyword-only.

## Returns

A result with decoded JSON in `data`, raw text in `stdout` and `stderr`, and `exit_code`. See [`atmos.run`](/functions/automation/atmos.run#returns) for output and error behavior.

## Examples

### Read a component as data

```python
station = atmos.describe(
    "component", "station",
    flags = {"stack": "dev", "format": "json", "provenance": False},
    output = "capture",
)
config = station.data
print(config["vars"]["location"])
```

This runs `atmos describe component station --format=json --provenance=false --stack=dev`. The
output is also available as raw JSON in `station.stdout`; JSON is the wrapper's default format.

### Pull one value with a query

```python
location = atmos.describe(
    "component", "station",
    flags = {"stack": "dev", "format": "json", "query": ".vars.location", "provenance": False},
    output = "capture",
)
print(location.data)
```

### List the stacks that define a component

```python
stacks = atmos.describe(
    "stacks",
    flags = {"components": "station", "sections": "vars", "format": "json"},
    output = "capture",
)
for stack_name in sorted(stacks.data.keys()):
    print(stack_name)
```

### Find affected components

```python
affected = atmos.describe("affected", flags = {"base": "origin/main", "include-dependents": True})
for item in affected.data:
    print(item["component"], "in", item["stack"])
```

The `base` key becomes `--base=origin/main`, which compares the working tree against the `origin/main` ref.

## Related

- [`atmos.run`](/functions/automation/atmos.run) runs any Atmos command from an argument list.
- [`atmos describe`](/cli/commands/describe/usage) documents every subcommand and flag.
- [Atmos Automation Language](/automation/language) and the [script step](/steps/type/script#calling-atmos-commands)