The Atmos Automation Language lets you turn affected components and stacks into build, test, and deployment tasks. Write your project logic once and run it locally or in CI.

Select work across your monorepo​

Monorepos bring related projects together. A single change can span an application, its shared configuration, and the components that depend on it. Knowing those relationships lets you focus validation and deployment on the parts of the repository that need them.

Atmos identifies affected components and stacks from its configuration and declared dependencies. The Atmos Automation Language puts those results in your script, where you can apply your project's build, test, and release rules.

Turn affected components into tasks​

Query the affected set, iterate over the results, and choose the commands to run for each component. You can use that set to select tests, prepare deployments, or run independent work in parallel.

The query wrappers capture output and request JSON by default. This applies to atmos.list, atmos.describe, and the config and stack config getters. Explicit formats and streaming options still take precedence.

Command results expose decoded JSON through data and retain raw stdout, stderr, and exit_code. The step library also exposes data, decoded from its primary value. Decoding happens only when accessed, so text results remain usable. Decoded collections are read-only and can be shared with parallel tasks.

How to Use It​

Run this script in an Atmos project with the comparison ref available locally:

result = atmos.describe(
    "affected",
    flags = {"base": "origin/main", "include-dependents": True},
)
for item in result.data:
    if not item.get("deleted", False):
        ui.info("{} in {}".format(item["component"], item["stack"]))

Use the records to select project commands or construct parallel tasks. Affected detection follows Atmos configuration and declared dependencies; the loop does not establish execution order between dependent components.

For individual child processes, exec.run and component.exec now accept timeout and retry directly. A timeout bounds the entire call, including retry delays. Only retry operations that are safe to repeat.

Get Involved​

Try the query defaults in your project automation and open an issue with feedback.

Atmos already manages Git hooks. Now you can write the checks themselves in the Atmos Automation Language, based on Starlark, and keep small checks inline beside the hook configuration.

Two checks from our own repository​

Two checks in the Atmos repository illustrate why this matters. One verifies that tracked symlinks resolve. The other limits the size of CLAUDE.md and agent instruction files, so guidance stays focused and detailed material moves to linked documentation.

We implemented both as Bash scripts. The symlink check uses shell parameter expansion to unpack Git's file listing and readlink to inspect targets. The size check pipes wc into tr to produce a number it can compare. Each script also formats its own error messages and instructions.

Writing these checks in Starlark gives them a common interpreter and filesystem API across operating systems. It is also part of a broader goal for Atmos: connect the tools developers use throughout delivery with readable, testable automation that runs locally and in CI.

Keep the checks with the hook​

Keep each check as a separate named step in atmos.yaml. Write the rules with loops, lists, filesystem functions, and structured errors. Atmos executes the Starlark script steps directly using its embedded interpreter.

The example below still asks Git which symlinks are tracked, but checks their targets through fs.exists. The size check uses fs.glob and fs.stat to read file metadata directly. Both report failures through the same error builder, including a hint about how to fix them.

Atmos provides the interpreter and these filesystem functions in one binary. The checks use the same language and filesystem API across machines, independent of the installed Bash version. External commands still have their own requirements; the symlink check requires Git, for example.

Hooks accept either a command or a steps list. Existing command hooks continue to work, and steps can use other registered types alongside scripts. This brings Git hook checks into the same execution model used by your other Atmos automation.

How to Use It​

Add two separate checks to atmos.yaml in your repository root:

git:
  hooks:
    pre-commit:
      steps:
        - name: check-symlinks
          type: script
          interpreter: starlark
          script: |
            entries = exec.run(["git", "ls-files", "-s", "-z"], output = "capture").stdout
            broken = []
            for entry in entries.split("\x00"):
                if not entry:
                    continue
                metadata, _, path = entry.partition("\t")
                if metadata.split(" ")[0] == "120000" and not fs.exists(path):
                    broken.append(path)
            if broken:
                (errors.build("Broken tracked symlinks")
                    .with_explanation("\n".join(broken))
                    .with_hint("Restore the targets or remove obsolete symlinks.")
                    .fail())

        - name: check-agent-file-sizes
          type: script
          interpreter: starlark
          script: |
            limits = [
                ("CLAUDE.md", 40000),
                (".conductor/*/CLAUDE.md", 40000),
                (".claude/agents/*.md", 25000),
            ]
            oversized = []
            for pattern, limit in limits:
                for path in fs.glob(pattern):
                    if not fs.exists(path):
                        continue
                    info = fs.stat(path)
                    if info.is_file and info.size > limit:
                        oversized.append("{}: {} bytes (limit {})".format(path, info.size, limit))
            if oversized:
                (errors.build("Agent instruction files exceed size limits")
                    .with_explanation("\n".join(oversized))
                    .with_hint("Move detailed guidance into linked docs; preserve mandatory instructions.")
                    .fail())

The symlink check asks Git which paths are tracked, then checks their targets in the working tree. The size check reads file metadata directly through Atmos. These checks inspect working-tree files, including unstaged changes.

Install the hook with atmos git hooks install:

atmos git hooks install

Run the same checks manually or in CI with atmos git hooks run:

atmos git hooks run pre-commit

Get Involved​

Try moving a small repository check into an inline script and open an issue if another filesystem operation would help.

The Atmos Automation Language, based on Starlark, lets us write that logic with ordinary functions and structured data, call the capabilities Atmos already provides, and test it with Atmos itself.

Give project automation a language​

Custom commands give a team familiar entry points, and workflows organize the process. The language gives you a way to express the decisions within it.

Declarative workflows and Makefiles give tasks and their dependencies a clear structure. A language is useful for the decisions between those tasks: iterate over affected projects, inspect a command's results, choose what runs next, and reuse the logic elsewhere.

In YAML workflows and Makefiles, that logic often lives in embedded shell or expressions inside configuration. The Atmos Automation Language gives it ordinary variables, loops, conditionals, functions, and structured data. You can read the logic directly and test a function independently of the deployment that calls it.

Keep workflows for orchestration and use the language where code expresses the work clearly. Atmos supplies the tools and conventions to execute both as part of the same delivery process.

Compose your delivery process​

Write the project logic in the Atmos Automation Language and call Atmos's existing capabilities from your script. Use consistent prompts, formatted output, and structured errors to give your team a familiar CLI experience. Reuse functions across your automation and run independent tasks in parallel.

The interpreter and test runner ship in the Atmos binary. Distribute your scripts with your project and invoke them from a terminal or a CI job. Configure the tools and credentials they use for each environment.

Direct access to the step library extends what these scripts can do. Calls such as steps.input, steps.http, steps.container, and steps.archive use the same fields as YAML steps and return values, metadata, and named outputs. You can compose those existing operations inside your functions and loops.

Scripts can run as standalone tools or within custom commands, workflows, and hooks. Steps keep their existing prerequisites: container operations need a configured runtime, prompts need a terminal or a default, and background-job controls require the workflow runner.

How to Use It​

Save this as select-service.star:

service = steps.input(prompt = "Service name?", default = "api").value
selection = steps.choose(
    prompt = "Environment?",
    options = ["dev", "prod"],
    default = "dev",
).value
ui.success("Selected " + service + " in " + selection)

Run it with atmos ./select-service.star. It prompts in a terminal and uses the configured defaults without one. Collect input before starting parallel tasks.

For a step type selected at runtime, call steps.run(type, **fields). See the step-library reference for available functions, result fields, and execution-context requirements.

Get Involved​

Try expressing part of your build, test, or deployment process in the language and open an issue if an operation needs better support in the language.

The Problem​

Templates are rendered over the whole step definition, including the script body. A step with a line such as print("{{ name }}") failed before it ever ran, and the error named an internal template instead of your step. The same rendering also ran over the environment Atmos inherited from your shell, so a variable that happened to contain braces could break an unrelated script step or reach child processes rewritten.

Custom commands also had input problems that were easy to miss:

• An argument value such as api,v2 arrived split into separate arguments.
• A flag declared with type: int showed up as a string flag and was missing from the values passed to steps.
• An optional argument without a default failed as if it were required.
• timeout: on script, shell, and Atmos steps was accepted but never enforced, and an unknown output: mode was silently ignored.

The Fix​

Tag any step field with !literal, in atmos.yaml or in a workflow file, and Atmos uses it exactly as written. It works for script, command, interpreter, working_directory, and individual env values, in sequential steps, parallel and matrix children, workflows, and lifecycle hooks.

Atmos now renders only the environment values you declare; everything inherited from your shell passes through unchanged. Template errors name the step, the field, and the included file, and suggest !literal when the body contains braces. Parallel and matrix children render with the same template functions as sequential steps.

For custom commands, argument values arrive exactly as typed, integer flags are typed values, and optional arguments can omit a default. Step timeout: values are enforced, and output: accepts only raw, log, viewport, or none.

How to Use It​

Mark a script body as literal when it contains braces:

commands:
  - name: greet
    description: Print a greeting
    arguments:
      - name: name
        description: Who to greet
        required: false
    flags:
      - name: times
        type: int
        default: 1
        description: How many greetings
    steps:
      - name: greet
        type: script
        interpreter: starlark
        timeout: 30s
        script: !literal |
          name = ctx.arguments["name"] or "world"
          for _ in range(ctx.flags["times"]):
              print("{{ Hello }}, %s!" % name)

Running atmos greet platform --times=2 prints {{ Hello }}, platform! twice. The script reads its inputs through ctx.arguments and ctx.flags, so nothing is interpolated into the source. See the script step reference for details.

Get Involved​

Tell us how you use templates and scripts together in GitHub Discussions, or open an issue if a step field still renders when you expect it to stay literal.

The same approach works for inventory reports, deployment checks, and other CLI apps. Atmos supplies the interpreter, typed flags, generated help, and automation functions so you can focus on the work your tool performs.

Your app can install pinned tool dependencies, run commands under configured cloud identities, and execute independent tasks in parallel. Return structured data for other tools to consume, and use error builders to report failures with explanations, hints, and examples through Atmos's own error formatting and reporting.

Build a release tool you can maintain and test​

As a release script grows, Bash plumbing can take over: parsing arguments and JSON, coordinating background processes, and handling errors between commands. The Atmos Automation Language gives you structured values, reusable functions, and parallel tasks for that work. Test your functions and command behavior with test steps, then run those checks locally and in CI.

Distribute the tool with your project and use the same entry point in both environments. Atmos runs it with the stacks, identities, and pinned tools you configure. See the release example for a tool that builds and pushes an image, then deploys with Terraform.

Run a .star file with Atmos​

Install Atmos and put it on your PATH. You can pass the script directly to Atmos, or put #!/usr/bin/env atmos on its first line, make it executable, and run it as ./my-tool.star on systems with shebang support.

Why Starlark?​

See why Atmos uses Starlark for the language choices and how they affect your scripts.

How to Use It​

Run your first app​

The summarize example reads a JSON service manifest and reports replica counts. It uses only functions built into Atmos; it needs no project configuration or external tools:

Save summarize.star and services.json from the example in the same directory, then run from that directory:

chmod +x summarize.star
./summarize.star services.json

It reports two services with five replicas in total. On systems without shebang support, use atmos ./summarize.star services.json.

Give the app an interface​

Declare arguments and flags with cli.command, then put the work in a main callback. This app accepts a service name and a typed replica count, checks the count, and reports the result:

Save it as capacity.star and run:

chmod +x capacity.star
./capacity.star api --replicas 3
./capacity.star --help

The first command prints api: 3 replicas x 4 workers = 12 workers. The second shows the required service argument, replica flag, and default. Help runs neither the validation callback nor main. A replica count of zero fails validation; --replicas=many fails integer parsing.

Use it locally and in CI​

Commit the app with your project and invoke the same file in your terminal and pipeline. Keep the CI or CD process's reusable logic in the app, and let the CI system control its triggers and approvals. Tools and credentials used by the app's subprocesses must be available in that environment.

Use ui for progress and log for diagnostics. UI messages go to stderr, leaving stdout available for data consumed by another process. Test your automation with script checks and test steps.

Next steps​

Build your first tool with the Custom CLI Apps guide. To run scripts as Atmos custom commands, workflow steps, or hooks, see Introducing Atmos Automation Language.

Native Helm releases in Atmos now capture that evidence at the moment of failure and fold it straight into the error: which pod is failing, what the container is reporting, and - at debug level - the crash log and recent events.

The Problem​

A failed readiness wait tells you that a release did not come up, but not why. The error names the release and namespace, yet the actual cause - a CrashLoopBackOff, an ImagePullBackOff from a bad registry mirror, a container exiting non-zero on a bad config value - lives on the pods, not in the release record.

So the cause is one kubectl session away. Except:

• In CI there is usually no interactive cluster access, so the run just fails with a timeout and no cause.
• When a release is configured to roll back or uninstall on failure, that recovery deletes the failing pods first. By the time anyone looks, the pod - and its logs - are gone.

The result is a dependency-ordered rollout that stops at a release nobody can diagnose from the output alone.

The Fix​

On a release failure, and before any rollback or uninstall runs, Atmos now enumerates the release's pods, finds the not-ready containers, and appends their diagnostics to the same error:

Error: failed to perform helm release operation
  workload diagnostics:
    pod keda-operator-7d9f  keda-operator CrashLoopBackOff (exit 1, 5 restarts)
      last log (keda-operator):
        panic: failed to load config: invalid duration "5x"
      events:
        BackOff  Back-off restarting failed container

The container-status summary (reason, exit code, restart count) is always included on failure. The log tail and the pod's recent events are added when you run at debug or trace level, so normal output stays concise.

To guarantee the evidence survives, Atmos now performs the configured on_failure rollback or uninstall itself, after collecting the diagnostics rather than before - the rollback and history-retention behavior you configure is unchanged, it just no longer races the diagnostics.

How to Use It​

There is nothing to enable. Any native Helm apply or deploy that fails readiness surfaces the diagnostics automatically. To include the log tail and events, raise the log level:

atmos helm apply keda -s plat-ue2-prod --logs-level=Debug

Diagnostics are best-effort: if the cluster cannot be reached, Atmos reports the original failure unchanged rather than masking it.

Get Involved​

This pairs with the native Helm release lifecycle controls. If there is a failure signal you want surfaced that Atmos does not yet capture, open an issue or discussion on GitHub.

Templating made configuration reusable. Custom commands gave teams their own CLI. The Atmos Automation Language is the next major step: you can program the process itself, with functions, control flow, structured data, and tests, using the capabilities already built into Atmos.

Build containers, ship them, and deploy them through the same scripts locally and in CI. Install pinned tools, assume configured identities, run commands, and parallelize independent work. Use consistent inputs, formatted output, and structured errors to make that automation useful to the whole team. It works for applications as well as infrastructure.

Write your code in a .star file and run it with atmos ./release.star, or embed it in custom commands, workflow steps, and hooks. The interpreter ships in the Atmos binary, together with the automation functions and test runner. Your scripts use the tools, credentials, and configuration you provide for each environment.

Use the same language inside stack manifests with the !starlark YAML function. Derive resource tags, names, and environment-specific settings from each component's configuration, and return typed values directly to YAML.

For standalone .star apps with their own arguments and help, see the Atmos interpreter announcement.

Keep your release process in one place​

Keep release logic with your project. Put it in functions, pass structured values between them, and test their behavior locally. Your CI pipeline invokes the same process your team uses during development, with its own triggers, credentials, and approvals.

Use custom commands for your team's entry points, workflows to compose the process, and lifecycle hooks for checks tied to component operations. They all run the same language and can load shared functions.

Run scripts inside Atmos​

Set type: script and interpreter: starlark on a step inside a custom command, workflow, or hook. The interpreter is included in Atmos.

Why Starlark?​

See why Atmos uses Starlark for the language's syntax, built-in capabilities, and execution model.

How to Use It​

Add an Atmos subcommand​

Save this configuration as atmos.yaml. It defines a capacity command with a --replicas flag and a script that calculates total worker capacity:

With Atmos installed, run from the directory containing that file:

atmos capacity --replicas 3

The command prints 3 replicas x 4 workers = 12 workers. The script reads ctx.flags["replicas"], converts it to an integer, and rejects counts below one. Run atmos capacity --help for the command's generated help. This example needs no stacks or external tools.

View the full example

Guard an operation with a hook​

A lifecycle hook runs automatically when Atmos reaches a component event. The owner-check example reads ctx.component.vars before a Terraform plan and requires the component to have an owner.

With Atmos and Terraform installed, run these commands from the example's directory:

atmos terraform plan api -s dev
atmos terraform plan api -s unowned

The dev stack passes the check and Terraform reports no changes. The unowned stack fails with Set an owner before planning api, stopping the plan. The example module has no providers or resources and needs no cloud credentials.

Share functions between scripts​

Move shared code into .star files. Include a script in a YAML step with script: !include scripts/plan.star, and use load() inside the script to import functions from other files. Imports resolve relative to the file containing the load() statement. See files and shared code.

The release-plan example loads a shared function and reads three components with at most two tasks running at once. It prints their configuration without deploying anything:

Derive configuration from the stack that uses it​

Define resource tags once and let each environment supply its own stage, region, and owner. Add the rule to a shared component definition:

vars:
  resource_tags: !starlark |
    return {
        "Environment": ctx.vars["stage"],
        "Region": ctx.vars["region"],
        "Owner": ctx.metadata.get("owner", "platform"),
    }

Atmos supplies a read-only context after imports, inheritance, and overrides. An inherited expression reads the consuming component's values: development gets development tags, and production gets production tags. Returned maps, lists, booleans, and numbers retain their types.

Use conditions, comprehensions, and helper functions to express configuration rules. Atmos resolves computed dependencies when accessed and reports cycles with the fields involved. Inspect the result with atmos describe component <component> -s <stack> before deploying.

The !starlark reference covers context fields, return types, and evaluation scope. Use automation scripts for commands and steps, and YAML expressions for computing configuration values.

Next steps​

Follow the custom command guide, workflow guide, or hook guide to add a script to your project. Use the testing guide to check its behavior and report failures.

Native Helm components now expose the two Helm 4 controls that resolve this - server_side_apply and force_conflicts - as release-policy settings and command-line flags, so a conflict clears in the normal atmos helm apply path.

The Problem​

Helm 4 applies release manifests with server-side apply by default, so field ownership is shared with any other actor that writes the same fields. Two situations routinely put another manager on a field a release also declares:

• A controller continuously reconciles an object it also received from a release, and takes ownership of fields the release sets.
• An object's managedFields ledger is orphaned - for example, a custom resource whose CRD hosts a conversion webhook loses its ledger when a conversion fails during a controller disruption. The next apply synthesizes a stand-in manager that owns the pre-existing fields, and a later release apply that changes those fields conflicts with it.

In both cases the apply reports a conflict and the install or upgrade aborts. Because Atmos set no conflict-resolution option, there was no way to clear it through the deploy path: you had to repair the object out of band and re-run. That breaks dependency-ordered rollouts, cannot be remediated in CI, and hid a control Helm 4 already implements.

The Fix​

Two keys are added to the native Helm release policy, alongside the existing wait, timeout, history, install, and upgrade controls:

components:
  helm:
    my-component:
      release:
        # Apply method. Omit to use the Helm default.
        server_side_apply: true
        # Resolve field-ownership conflicts by overwriting the contested
        # fields and becoming their sole manager. Opt-in; default false.
        force_conflicts: false

With force_conflicts enabled, a release apply that meets a field owned by another manager overwrites the contested fields and becomes their sole owner, so the release reaches a successful completion state and its dependents proceed. It is opt-in by design: forcing overrides other managers, so a controller that legitimately co-owns a field loses it on the next apply. That trade-off is yours to make per component, which is why the default leaves conflicts fatal and visible.

server_side_apply accepts auto, true, or false. Omitting it preserves the Helm default - server-side apply on install, and the prior release's method on upgrade - so a release that sets neither key behaves exactly as before.

Both settings resolve through the same path as the rest of the release lifecycle: stack type defaults, base-component inheritance, concrete component configuration, and command-line override. A release-wide value is the common case, and the per-phase install and upgrade blocks can override it when first install and later upgrades need different behavior. The configured values are validated before any chart download or cluster mutation.

How to Use It​

Set the policy in a stack for steady-state behavior, or force a single recovery apply from the command line without editing configuration:

# One-off recovery: take ownership of the contested fields and continue.
atmos helm apply my-component -s plat-ue2-prod --force-conflicts

# Override the apply method for this run (a bare flag selects true).
atmos helm apply my-component -s plat-ue2-prod --server-side-apply=false

The --force-conflicts and --server-side-apply flags are available on apply and deploy, and take precedence over stack release configuration.

Get Involved​

See the native Helm release lifecycle documentation for the full policy reference. If you hit a server-side apply scenario this does not cover, open an issue or discussion on GitHub - we would like to hear about it.

The Problem​

atmos scaffold generate --update and atmos init --update compute a three-way merge for every file the template still generates: what changed upstream, layered onto what you've customized locally. But that merge only ever ran for files that exist on both sides. Two real gaps followed from that:

• When the template stopped generating a file, --update never noticed. The stale file just sat there, untouched, on every future update, forever.
• When you deleted a file yourself — because you didn't need it, or you'd replaced it with something else — the next --update silently wrote it straight back, as if your deletion had never happened.

The Fix​

--update-strategy=rendered now detects a file the template stopped generating and removes it, but only when your copy still matches exactly what the template last produced. If you'd edited that file since, --update doesn't guess: it surfaces an unresolved conflict instead, the same way a genuine merge conflict does, so you decide whether to keep it or let it go. --update-strategy=tracked can't offer this part safely — there's no reliable way to know which files in your project's own git history actually belonged to the template versus anything else that happened to live there.

Independently of strategy, --update also stops silently overwriting a deletion you made yourself. Both tracked and rendered now check whether a file was previously generated before recreating it, and leave your deletion in place if so. Pass --recreate-deleted to opt back into the old always-recreate behavior — it's deliberately its own flag rather than folded into --force, since --force already means "the template's version wins" for merge conflicts, and tying file recreation to it would make "resolve conflicts manually" and "recreate what I deleted" mutually exclusive. --force does, however, now resolve a deletion conflict the same way it resolves any other: if the template removed a file you'd since edited, --force deletes it anyway instead of leaving you stuck with a conflict only manual cleanup could clear.

How to Use It​

# A file the template no longer generates is removed automatically on --update,
# as long as you haven't edited it -- otherwise you'll get a conflict to resolve.
atmos scaffold generate my-template ./my-project --update --update-strategy=rendered

# Recreate a file you deleted instead of leaving the deletion in place.
atmos scaffold generate my-template ./my-project --update --recreate-deleted

# Force past a deletion conflict -- the template's choice (delete it) wins.
atmos scaffold generate my-template ./my-project --update --update-strategy=rendered --force

Get Involved​

See the atmos scaffold generate and atmos init docs for the full flag reference. Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

Small pieces of reference data — license choices, region codes, a naming convention lookup — show up constantly in real scaffold templates, and they rarely stay confined to one field. A select field needs them as {label, value} options; a file elsewhere in the same template needs the raw table to look values up by key. Duplicating that table by hand, once per field that needs it, means every future edit has to find and update every copy — and a missed one quietly drifts out of sync with the rest. Beyond reference data, templates also commonly need small dynamic values — the user's git branch or commit SHA, an environment variable, a random suffix for a resource name — with no way to derive any of them automatically.

The Fix​

scaffold.yaml now resolves a set of Atmos YAML functions — the same explicit-tag mechanism stack manifests already use — anywhere it currently accepts a literal value: options:, a type: computed field's value:, or a matrix: axis.

• !include/!include.raw pulls in a local or remote file, optionally reshaped with a YQ filter.
• !env reads an environment variable, !random generates a random number, and !cwd reads the current working directory.
• The !git.*/!repo-root family exposes the current git branch, commit SHA, repository name, and more.
• !literal preserves a value exactly as written, bypassing scaffold's own template evaluation — useful when a value legitimately contains {{ }} and shouldn't be treated as a template expression.

spec:
  fields:
    - name: license
      type: select
      options: !include "./lib/licenses.yaml '. | to_entries | map({\"label\": .value.full_name, \"value\": .key})'"

    - name: license_lookup
      type: computed
      value: !include ./lib/licenses.yaml

    - name: branch
      type: computed
      value: !git.branch

A locally-included file that exists solely to be included is automatically excluded from generated output, the same way scaffold.yaml itself is. atmos scaffold validate resolves everything too, not just generate, so a missing file, a bad filter, or a malformed value is caught up front.

Not every YAML function is available here: anything that needs real stack, component, or backend context (!terraform.state, !store, !secret, and similar) is rejected with a clear error instead. A template's scaffold.yaml is often resolved just to show its name and description in atmos scaffold list or the interactive picker — before a user has chosen or generated anything — so only functions that are safe to run in that situation are supported.

The !exec function is excluded for a different reason: it needs no stack context at all, but scaffold.yaml is resolved for every template configured in atmos.yaml just to populate the list and picker, not only the one a user actually generates — so allowing shell execution there would let any configured template, including a shared or vendored one, run arbitrary code merely by being listed.

How to Use It​

Add any of the functions above anywhere options:, a computed field's value: (see Computed Fields), or a matrix axis currently accepts a literal value. See the full examples/scaffolding-yaml-functions example, or the Loading External Data with !include and Other YAML Functions section of the atmos scaffold generate docs.

Get Involved​

See the atmos scaffold generate docs for the full reference, or open an issue with feedback.

By default, --use-mocks now treats mocks as fallbacks. Real state wins whenever it exists, and a mock fills in only for a component that has not been provisioned or an output that is missing.

The Problem​

Mocks were designed to let a plan or describe component run before its dependencies exist. In practice, a stack is usually partly deployed. Turning mocks on replaced every !terraform.state and !terraform.output lookup with literal values, so a plan against a half-built environment showed fake IDs for resources that already had real ones. The only alternative was to turn mocks off and fail on the components that were not there yet.

The Fix​

The behavior is configurable. In the new default fallback mode, each lookup resolves in this order:

1. The real value, when the referenced component's state exists and declares the output.
2. The component's mock, when the state is not provisioned or the output is missing.
3. A YQ // default in the expression, if one is present.
4. The same result as without mocks: the not-provisioned error for a component that was never applied, or null for an output missing from applied state.

Mocks never hide real problems. Credential, network, and backend failures still fail the command instead of quietly returning a mock value. As before, only atmos terraform plan and atmos describe component accept --use-mocks; every other Terraform subcommand, such as apply, deploy, and destroy, rejects it. Map outputs are merged: a mock fills keys that are missing from a real map output, while every value present in real state wins.

The other mode, always, keeps the previous behavior for lookups that must not depend on what is deployed, such as describing a component on a machine without cloud credentials. In always mode, !terraform.state and !terraform.output lookups resolve from mocks only and never initialize Terraform, authenticate, or read a backend for the components they reference. A plan still runs Terraform against the component being planned, with that component's own backend and provider credentials. Choose the mode per run with the flag, or set a project default with mocks.mode, as shown below.

How to Use It​

Declare mocks on the producer component as before:

components:
  terraform:
    vpc:
      mocks:
        vpc_id: vpc-local
        private_subnet_ids: [subnet-a, subnet-b]

    app:
      vars:
        vpc_id: !terraform.state vpc vpc_id

Then pick the mode per run, or set a project default:

# Real state where it exists, mocks for the gaps.
atmos terraform plan app -s dev --use-mocks

# Lookups use mocks only, with no backend reads or credentials for them.
# The plan itself still uses app's own backend and provider credentials.
atmos terraform plan app -s dev --use-mocks=always

components:
  terraform:
    mocks:
      mode: always   # fallback (default) | always

The mocks.mode setting can also be set with ATMOS_COMPONENTS_TERRAFORM_MOCKS_MODE. Attach a mode to the flag with =, because --use-mocks always does not select one. An explicit mode passed with the flag, such as --use-mocks=fallback or --use-mocks=always, wins over the environment variable, which wins over atmos.yaml. A bare --use-mocks turns mocks on and keeps the configured mode.

Upgrading​

This changes what a bare --use-mocks does, so the new default is tied to config editions. Projects pinned to an edition before 2026-10-01 keep the previous mocks-only behavior with no changes. Unpinned projects, and projects that move their edition forward, get the fallback behavior. To keep mocks-only regardless of edition, set mocks.mode: always or pass --use-mocks=always.

See resolution modes for the full details.

Get Involved​

Try the provider-free component mocks example, which walks through both the fallback and always flows. Questions and feedback are welcome in GitHub Discussions or the SweetOps Slack.

The Problem​

Just-in-time access is the right default for privileged roles, but the activation step lands on the operator every single session, outside the tool they actually came to use. You want to run a plan against production; first you have to remember the role definition id, the scope, a justification, and the sequence of REST calls to turn your eligibility into an active assignment - and redo it when the window expires. Worse, nothing downstream benefits from a single place that performs the elevation: the credential your tooling consumes is the same either way, so there is no natural seam to hang "activate my role, then run" on. Atmos already modeled the two things this needs - becoming something more privileged through identity chaining, and credential time-boxing - but Azure only had the azure/subscription identity. There was no way to express the elevation at all.

The Fix​

A new azure/pim-role identity chains from an existing Azure identity and, on authentication, runs the Azure Resource Manager PIM self-activation for a role you are eligible for - scoped and time-boxed by config. Because the elevation lives in the identity chain, every consumer inherits it with no extra wiring: atmos terraform, atmos auth exec, the AKS kubeconfig exec plugin, and MCP servers all just see the role active.

Unlike assuming a role, azure/pim-role mints no new credentials. Azure RBAC evaluates roles by object id at request time, not as token claims, so the activation elevates the principal you already authenticated as - server-side - and the identity hands back the parent credentials unchanged, now carrying the active role. That is what lets it sit transparently anywhere in a chain.

It is also careful about not being noisy:

• It does not re-request on every command. If an active assignment already covers the scope, it returns immediately instead of filing another request and tripping PIM throttling.
• It resumes instead of duplicating. If a request for the same role and scope is already waiting on an approver, a later run attaches to that pending request rather than starting a new one.
• It refuses clearly when it cannot proceed. A missing eligibility is reported as "not eligible" (this activates an eligibility, it does not grant one), distinct from an activation that failed. In a non-interactive context with no justification, it fails fast and tells you how to supply one.

How to Use It​

Add a azure/pim-role identity that elevates from an identity you already have:

auth:
  identities:
    azure-dev:
      kind: azure/subscription
      via:
        provider: azure-interactive
      principal:
        subscription_id: "00000000-0000-0000-0000-000000000000"

    prod-contributor:
      kind: azure/pim-role
      via:
        identity: azure-dev          # elevate from who I already am
      principal:
        role_definition_id: "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c"
        scope: "/subscriptions/00000000-0000-0000-0000-000000000000"
        duration: "8h"               # converted to ISO-8601; Azure enforces the role's policy maximum
        justification: "planned change window"

Then authenticate or run as usual - the role activates as part of the chain:

atmos auth login --identity prod-contributor
atmos auth exec --identity prod-contributor -- terraform plan

Need a different reason for a specific run? Pass the --justification global flag (or set the ATMOS_AUTH_JUSTIFICATION environment variable) - it overrides the configured default:

atmos auth exec --identity prod-contributor --justification "incident INC-123" -- terraform apply

In a non-interactive context (CI, a running MCP server) with no justification available at all, the login fails fast and tells you to pass --justification or set ATMOS_AUTH_JUSTIFICATION. If a role requires approval, the login bounds its wait and shows progress; a later invocation picks up the pending request instead of starting over.

This covers Azure resource roles. Entra directory roles and PIM for Groups activate through different APIs and will be separate identity kinds.

Get Involved​

The azure/pim-role identity is part of the broader Atmos Auth effort to make least-privilege, just-in-time access something you configure once and forget. If you run PIM in Azure, try it against an eligible role and let us know how it fits your workflow in GitHub Discussions.

The Problem​

atmos scaffold generate --update and atmos init --update compute a three-way merge for every existing file: what changed in the template, layered onto what you've customized locally. If that merge would touch more than 50% of a file's lines, it bails out entirely — no conflict markers, no partial result, just a hard failure and the file left untouched. That 50% ceiling was hardcoded, with no flag to raise it, even though a large conflict is often exactly the kind of thing a person wants surfaced for manual review rather than blocked outright.

The Fix​

--max-changes on both commands controls that same conflict-percentage threshold. The default stays 50 — no behavior change if you don't pass it. 0 disables the check entirely: the merge always proceeds and writes conflict markers for you to resolve, instead of refusing the update.

One nuance worth understanding before you reach for a specific number: the change percentage this is compared against isn't itself capped at 100. When your local edits and the template's changes both diverge significantly from the common base, the computed percentage can climb well past 100% (200%+ in some cases). That means only --max-changes=0 is a guaranteed "never fail on this" setting — raising it to 100, 200, or higher only makes a hard failure progressively less likely, it doesn't rule one out. If what you actually want is "always give me conflict markers, never a hard failure," reach for 0, not a large number.

How to Use It​

# Default behavior is unchanged: fails if a merge would touch more than 50% of a file.
atmos scaffold generate my-template ./my-project --update

# Always get conflict markers instead of a hard failure.
atmos scaffold generate my-template ./my-project --update --max-changes=0
atmos init --update --max-changes=0

# Or configure it once via environment variable.
ATMOS_SCAFFOLD_MAX_CHANGES=0 atmos scaffold generate my-template ./my-project --update
ATMOS_INIT_MAX_CHANGES=0 atmos init --update

Get Involved​

See the atmos scaffold generate and atmos init docs for the full flag reference. Have feedback on this feature? Open an issue or join the conversation in the Cloud Posse community Slack.

The Problem​

Exception capture previously depended on configuring a separate Sentry destination. Enabling Atmos Pro for a stack did not automatically send CLI exceptions to Pro, leaving failures disconnected from the execution records already uploaded there.

The Fix​

The automatic Pro exception reporter sends failures from GitHub Actions when the effective settings.pro.enabled is true, using fresh GitHub OIDC credentials and the configured Pro base URL. Separately configured Sentry destinations continue to receive events with the same IDs and fingerprints.

Resolved component metadata, including inherited stack defaults, becomes unprefixed Sentry tags. A production presence tag becomes production: "true"; a team: platform label becomes team: "platform". Events also include stack/component identity and the execution ID used by Pro uploads, with Atmos's existing masking applied.

How to Use It​

Enable Pro in atmos.yaml for invocation-wide reporting, or use the existing stack/component Pro setting:

settings:
  pro:
    enabled: true

Grant the GitHub Actions workflow id-token: write permission:

permissions:
  contents: read
  id-token: write

Upgrade behavior: existing stacks with settings.pro.enabled: true now send CLI exceptions automatically in eligible GitHub Actions runs. To retain the previous behavior while keeping other Pro features, explicitly opt out:

settings:
  pro:
    enabled: true
    errors:
      enabled: false

The ATMOS_PRO_ERRORS_ENABLED=false environment override also disables reporting and takes precedence over component settings. Edition pins do not suppress this new behavior. Reporting failures preserve the command's exit code, with a two-second delivery timeout and a shared two-second shutdown flush.

The CLI contract covers successful ingestion and authentication rejection; Pro's provider verification and persisted-tag assertions are tracked in issue #3219.

Get Involved​

See the reporting configuration and tag precedence for details, and open an issue with feedback about exception reporting.

Enable toolchain.frozen_lock_file: true in CI and security-sensitive environments to reject those missing entries and prevent lockfile writes. That way, you can prepare and review lockfile updates before running CI.

This update makes project configuration consistent across invocation directories and keeps automatic installs from changing declared dependencies. The same project paths and declarations apply whether a developer or CI runs the command.

The Problem​

Relative toolchain paths could follow the directory where you invoked Atmos. A command run from a component directory could therefore look for a different version manifest or use a different installation directory than the same command run from the project base.

Automatic installation also used the declaration-writing behavior of an explicit install command. Running an infrastructure command could leave a change in .tool-versions, even though you had not asked to change the project's dependencies.

The Fix​

Toolchain paths now resolve from the configured project base, and automatic installs leave declared versions unchanged.

For example, with /work/infra as the configured project base, Atmos reads /work/infra/.tool-versions even when invoked from /work/infra/components/vpc. A configured install_path: .tools resolves to /work/infra/.tools from either directory. The same rule applies to relative versions_file and lock_file settings.

Binaries still use shared XDG cache storage by default. When Atmos installs a version of itself outside a project, it now keeps installation metadata there too, unless you explicitly override the installation path.

How to Use It​

Existing projects get the path and declaration fixes without adding configuration. Continue running your usual Atmos commands; when they need to install a tool automatically, the project's declarations remain unchanged. Use explicit toolchain management commands when you intend to add or change those declarations.

Use the toolchain environment overrides to select a different manifest or installation directory without editing project configuration. For example, ATMOS_TOOLCHAIN_INSTALL_PATH=/shared/atmos-tools atmos toolchain install installs binaries in the supplied directory even when invoked outside the project.

Automatic installs can still update resolved artifact metadata in the existing toolchain.lock.yaml: they record missing version or platform entries after successful installation, preserve matching entries, and fail on checksum mismatches. The distinction is between declaring a dependency and recording the artifact used to satisfy it. See automatic installation and lockfiles for details.

Compatibility​

If you relied on toolchain paths relative to the invocation directory, adjust them relative to the project base or use absolute paths. These behavior fixes apply to every config edition; pinning an older edition does not restore the earlier path or declaration-writing behavior.

The existing lockfile defaults still depend on your edition. Editions before 2026-08-05 retain use_lock_file: false; set it explicitly to enable ordinary lockfile use. Frozen mode remains opt-in and requires verification regardless of that setting.

Get Involved​

Try running your existing commands from a project subdirectory and check that automatic installs leave .tool-versions unchanged. Share any unexpected behavior in GitHub Discussions.

The Problem​

Templating and scaffolding tools all hit the same shape of problem eventually: a value the generated output needs isn't something the user should be prompted for at all — it's derived from answers they already gave. Ask for a list of regions, then only ask for a primary region when there's more than one; when there's exactly one, it's the primary by definition, no prompt needed. That derivation logic is simple once, but a scaffold template has no single place to put it. It gets pasted into every file that references the value, and every copy has to independently stay in sync with the same conditional. Miss one, or get the fallback logic subtly wrong in one file, and that file quietly disagrees with the rest of the generated project.

The Fix​

A new type: computed field declares a value once — either derived from other answers via a value: Go-template expression, or a plain literal (string, number, boolean, list, or map) used as-is — and is never itself prompted for or settable with --set. A string is only treated as an expression when it actually contains a template action; a plain string like hello is a literal too, same as any other type:

spec:
  fields:
    - name: regions
      type: multiselect
      options: [us-east-1, us-west-2, eu-west-1]
    - name: primary_region_select
      type: select
      options: answers.regions
      when: "size(answers.regions) > 1"
    - name: primary_region
      type: computed
      value: "{{ ternary answers.primary_region_select (index answers.regions 0) (gt (len answers.regions) 1) }}"

primary_region derives its value exactly once, and .Config.primary_region is then usable everywhere .Config is — file content, target: path templates, and matrix: axes — with no per-file fallback logic to keep in sync. Computed fields evaluate in declaration order, after every regular field's answer is already final, so a computed field can reference any regular field regardless of where it's declared, and any earlier-declared computed field's own result.

A computed field's value: doesn't have to be an expression at all — a plain literal works too, useful for a small hand-authored reference table shared across every file in the template:

- name: provider_version_pins
  type: computed
  value: {aws: "~> 5.0", azurerm: "~> 3.0", google: "~> 5.0"}

provider_version_pins is stored exactly as written, with no template rendering, and is reachable the same way as any other computed field: .Config.provider_version_pins.

How to Use It​

Add a type: computed field to any existing scaffold.yaml, following the shape above, and reference its name from .Config in any file the template generates:

atmos scaffold generate <template> <target> --set regions=us-east-1,us-west-2

See the Computed Fields section of the atmos scaffold generate docs for the full set of validation rules (value: is required on a computed field and rejected on every other type; required:/default: are both rejected on a computed field) and the ordering constraints that keep a computed field's dependencies resolvable.

Get Involved​

See the atmos scaffold generate docs for the full reference, or open an issue with feedback.

The Problem​

The matrix: field already expands a single declared file into one generated file per selected value — pick three environments, get three files, from one template file. But real templates aren't single files; they're whole directories. A components/ tree with a dozen resources that needs to exist under every environment couldn't be matrixed as a unit — only file by file, one spec.files[] entry per file, each with its own repeated matrix: and target:. Skipping a directory recursively (docs that only ship when an answer opts in, a cloud-specific subtree that only applies to one provider) had the same problem in miniature: one when:-gated entry per file, duplicated across every file the directory contained.

The Fix​

The spec.files[].path field can now be a glob pattern instead of a literal path — *, ?, [...], ** for any depth, and {a,b} brace expansion — matched against every file the template discovers. One entry now covers an entire directory:

spec:
  files:
    - path: "docs/legacy/**"
      when: "answers.include_legacy_docs"

The when: field still evaluates exactly as it does for a single file — it just now applies to every file the glob matches, at any depth, recursively, with no per-file repetition. When more than one entry's path: matches the same file, the last one declared wins, the same precedence .gitignore/CODEOWNERS use: write broad patterns first, specific overrides after.

Combine a glob path: with matrix: and target: to duplicate an entire directory once per combination, the same way a single file already could:

spec:
  files:
    - path: "components/**"
      target: "environments/{{ .matrix.env }}/{{ .file.RelPath }}"
      matrix:
        env: [dev, staging, production]

Since a glob can match many files, target: needs to know which matched file an output came from — .file.RelPath is that file's own path with the glob's literal prefix stripped (so components/vpc/main.tf becomes vpc/main.tf), available in target: and the file's own content alongside .matrix.<axis>. A components/ directory with vpc/main.tf and eks/main.tf produces six files across three environments — each preserving its own relative position under every environment.

How to Use It​

The scaffolding-directory-matrix example is a minimal, runnable template — a two-resource components/ directory duplicated once per selected environment:

cd examples/scaffolding-directory-matrix
atmos scaffold generate example ./my-project --set environments=dev,staging

This generates four files: environments/dev/vpc/main.tf, environments/dev/eks/main.tf, and the same pair under staging/ — two full copies of components/, one per selected environment, without listing vpc/main.tf and eks/main.tf individually in scaffold.yaml. Add a glob path: to any spec.files[] entry in your own templates — with when: alone to skip a directory, or with matrix: and .file.RelPath in target: to duplicate one.

Get Involved​

See the atmos scaffold generate docs for the full reference, or open an issue with feedback.

The Problem​

Atmos AI let you talk to your infrastructure through a fixed set of API providers. If you wanted to try a cheaper or non-US model - route through an aggregator, run DeepSeek directly, or use a GLM model from Z.AI - you were out of luck unless you were willing to point the generic OpenAI provider at a hand-copied base URL and hope the defaults lined up. There was no first-class way to say "use OpenRouter" and get a sensible model, API-key variable, and endpoint out of the box.

The Fix​

Atmos AI adds three OpenAI-compatible API providers you can select by name:

• OpenRouter (openrouter) - a router that fronts hundreds of models behind one API key. Switch models by changing the model slug (anthropic/claude-sonnet-4-5, openai/gpt-4o, deepseek/deepseek-chat, ...) without touching anything else.
• DeepSeek (deepseek) - the DeepSeek API directly, including deepseek-reasoner for the reasoning model. Low cost for a lot of everyday infrastructure questions.
• Z.AI (zai) - Zhipu's GLM models over their OpenAI-compatible endpoint.

Each one behaves like every other Atmos AI provider: set an API key with the !env function, and optionally override the model, base_url, or token limits. Because they are OpenAI-compatible, they work everywhere the existing providers do - atmos ai ask, atmos ai chat, and the --ai flag.

How to Use It​

Add the provider under ai.providers in atmos.yaml and select it as the default:

ai:
  enabled: true
  default_provider: openrouter
  providers:
    openrouter:
      model: "deepseek/deepseek-chat"   # any provider-prefixed slug
      api_key: !env "OPENROUTER_API_KEY"

    deepseek:
      model: "deepseek-chat"            # or "deepseek-reasoner"
      api_key: !env "DEEPSEEK_API_KEY"

    zai:
      model: "glm-5.3"
      api_key: !env "ZAI_API_KEY"

Then ask away:

export OPENROUTER_API_KEY=sk-or-...
atmos ai ask "What stacks and components do we have?"

See the full list of options on the AI providers configuration page.

Get Involved​

The provider list will keep growing as the model landscape shifts. If there's an OpenAI-compatible provider you want to see as a first-class name in Atmos, open an issue or a pull request on cloudposse/atmos - adding one is a small, well-templated change.

The Problem​

Atmos AI could reuse a locally installed coding-agent CLI - Claude Code, OpenAI Codex, GitHub Copilot - instead of an API key, but the popular open-source opencode agent wasn't one of them. opencode users had to fall back to configuring a raw API provider, which meant a second credential to manage and gave up opencode's own model selection and MCP setup.

The Fix​

Atmos AI adds opencode as a CLI provider. Point Atmos at it and every atmos ai command runs through your existing opencode installation and whichever model provider you've authenticated there - no API key in atmos.yaml:

• Reuses your opencode auth and model configuration (opencode auth login).
• Full MCP pass-through: MCP servers you declare in atmos.yaml are handed to opencode automatically, with auth-requiring servers wrapped in atmos auth exec and the Atmos toolchain on PATH. Atmos writes a temporary config and points opencode at it via OPENCODE_CONFIG, so your own opencode.json is never touched.
• Participates in auto-detection: with ai.enabled: true and no default_provider, Atmos finds the opencode binary on your PATH and uses it.

How to Use It​

Select it as the default provider (or let auto-detection find it):

ai:
  enabled: true
  default_provider: opencode
  providers:
    opencode:
      # optional - opencode's provider/model slug; defaults to opencode's own default
      model: "anthropic/claude-sonnet-4-5"

Then ask away - opencode handles the model call and any MCP tools:

atmos ai ask "Which components changed in the dev stack?"

See the AI providers configuration page for the full CLI-provider reference, including the MCP pass-through behavior.

Get Involved​

opencode joins Claude Code, OpenAI Codex, and GitHub Copilot as bring-your-own-subscription CLI providers. If there's another local coding agent you'd like Atmos to drive, open an issue or a pull request on cloudposse/atmos.

The Problem​

A repository can contain many component sources, mixins, and targets. Fetching these one at a time leaves the network idle between jobs and makes a large update hard to follow. Overlapping destinations also mean downloads cannot simply copy files whenever they finish.

The Fix​

Vendor pull prepares up to four packages at once and installs them in declaration order. Local sources wait for earlier writes before being read. Vendor update checks upstream versions concurrently and preserves the order and formatting of manifest edits.

The shared progress display shows active phases, download percentages when the total size is known, retries, and completed results. A ready package is waiting for its turn to install. The overall bar advances during downloads with known sizes and when packages become ready, with equal weight for preparation and installation. The completed count advances only after processing finishes. CI receives plain result lines, and structured update reports stay on stdout.

The vendor clean command displays relative paths and preserves every lock entry when removing vendored files. Recorded versions, checksums, and provenance remain available for the next pull. Fully cleaned packages reinstall without drift warnings; partial deletion and modified files still trigger checks.

How to Use It​

atmos vendor pull --max-concurrency 8
atmos vendor update --check --max-concurrency 8
atmos vendor update --pull --max-concurrency 8

Set vendor.max_concurrency in atmos.yaml or use ATMOS_VENDOR_MAX_CONCURRENCY. Explicit flags take precedence over the environment and configuration. Set one worker for serial execution.

Projects with an edition pin before 2026-09-15 keep one worker by default. All editions receive the progress display, and explicit concurrency settings override the pin.

Get Involved​

Try the commands on your component catalog and share feedback in Atmos GitHub Discussions.