Skip to main content

atmos.stack

The atmos.stack function runs atmos stack through the current Atmos executable. Use it to read and edit component values in stack manifests with dot-notation paths, format manifests, and validate stacks from automation.

Usage​

atmos.stack(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Get operations default to JSON and captured output. Read result.data for the typed value or result.stdout for raw JSON. Use flags = {"format": "raw"} for unquoted text and output = "stream" to display output live. Other operations retain streaming output. See query defaults.

Subcommands​

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

SubcommandPurpose
getRead a component-relative value from a stack.
setSet a component-relative value in the manifest that defines it.
deleteDelete a component-relative value from the manifest that defines it. Also available as del and unset.
formatFormat the manifest files that define a stack component. Also available as fmt.
validateValidate stack manifest configurations.
schemaPrint the atmos-manifest JSON Schema.
configRead, edit, and list component config in stack manifests, with its own get, set, delete, format, and list subcommands.

See the atmos stack command reference for the complete list of subcommands and flags.

Arguments​

*positionals

(Optional) Strings placed on the command line right after stack, in order: the subcommand and its positional arguments, such as a dot-notation path and, for set, the new value. Every value must be a string, so pass "3" rather than 3 as a value.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "stack" becomes --stack, and registered shorthands such as "s" and "c" resolve to --stack and --component. Common keys for this command are "stack", "component", "file", and, for set, "type".

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 data, stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

Read a value from a component​

location = atmos.stack("get", "vars.location", flags = {"stack": "dev", "component": "station"}, output = "capture")
print(location.data)

The value is written to stdout. The command reports which manifest the value comes from on stderr.

Change a value in the manifest that defines it​

atmos.stack(
    "set",
    "vars.location",
    "Oslo",
    flags = {"stack": "dev", "component": "station"},
)

Atmos finds the manifest file that defines the effective value and edits it in place, keeping comments and YAML functions. Pass flags = {"file": "stacks/deploy/dev.yaml"} to target one file explicitly.

Validate stacks as a gate​

result = atmos.stack("validate", output = "capture", check = False)
if result.exit_code != 0:
    fail("Stack validation failed:\n" + result.stderr)
ui.success("All stacks validated successfully.")

Compare a value across stacks​

def location_of(stack):
    out = atmos.stack("get", "vars.location", flags = {"stack": stack, "component": "station"}, output = "capture")
    return out.data

for stack in ["dev", "staging", "prod"]:
    ui.info(stack + ": " + location_of(stack))

Related​