Skip to main content

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​

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.

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.

SubcommandPurpose
componentShow configuration details for a component in a stack.
stacksDisplay configuration for stacks and their components.
affectedList components and stacks affected by two Git commits.
dependentsList components that depend on a given component. Also available as dependants.
localsDisplay locals from stack manifests.
workflowsList workflows and their associated files.
configDisplay the final merged CLI configuration.
editionDisplay the active edition pin and the defaults it rolls back.

See the atmos describe command reference 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. 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 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 for output and error behavior.

Examples​

Read a component as data​

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​

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​

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​

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​