The Problem​

• JIT auto-provisioning and atmos vendor pull had two separate, non-overlapping implementations of "download a source." Only the vendor-pull one understood oci://.
• Registries publishing modules via OpenTofu's native "install modules from OCI registries" format ship their content as a ZIP-archive layer, not the tar+gzip layer Atmos expected. Pulling one failed with archive/tar: invalid tar header regardless of which path you used.
• OCI pulls also had no timeout, so a slow or unresponsive registry could hang a command indefinitely.

The Fix​

• The OCI-fetch implementation moved into a shared pkg/oci package so both atmos vendor pull and JIT auto-provisioning use the same implementation instead of two divergent ones.
• The puller now recognizes ZIP-layer OCI artifacts (OpenTofu's module-package format) in addition to Atmos's own tar+gzip format, with the same directory-traversal and decompression-size guards either way.
• OCI pulls are now bounded by a 10-minute timeout, matching the existing go-getter download path.

How to Use It​

components:
  terraform:
    my-component:
      source:
        uri: "oci://ghcr.io/my-org/my-module:v1.2.0"
      provision:
        workdir:
          enabled: true

Running atmos terraform plan my-component -s <stack> now auto-provisions the source before running, the same way it already does for git and HTTP sources.

Authentication works the same way it already does for atmos vendor pull: your existing registry credentials are picked up automatically, with an anonymous fallback if none are configured.

Get Involved​

See the Workdir Provisioning docs for the full provision.workdir reference, or open an issue if you hit an OCI registry format that still doesn't extract cleanly.

The Problem​

• Bulk execution flags --all and --affected landed on apply/plan/destroy when Terraform bulk execution moved onto the scheduler-backed dependency graph, but init was left out.
• Reinitializing every component after a provider upgrade, or bootstrapping a new environment, meant looping atmos terraform init <component> -s <stack> by hand.
• The scheduler also capped concurrency to 1 for any subcommand it didn't explicitly recognize, so there was no way to route around it either.

The Fix​

• terraform init now accepts --all, --affected, --max-concurrency, --failure-mode, and --log-order, matching destroy.
• Init keeps the natural forward dependency order — prerequisites before dependents — unlike destroy, which reverses the graph.
• Concurrent bulk init automatically disables the shared provider plugin cache for worker subprocesses, since sharing it isn't safe across concurrent terraform init runs.

How to Use It​

# Initialize every Terraform component, in dependency order
atmos terraform init --all -s prod

# Initialize only the affected components
atmos terraform init --affected

# Run independent components concurrently
atmos terraform init --all -s prod --max-concurrency 4

# Keep going past a failed component instead of stopping
atmos terraform init --all -s prod --failure-mode keep-going

Get Involved​

Have a bulk-execution flag you'd like to see on another command? Open an issue or join the discussion on GitHub.

The Problem​

This surfaced while migrating a Terragrunt Lambda example (Lambda + DynamoDB + IAM role) to Atmos. The source unit used a before_hook "package" wrapping scripts/package.sh, which itself wrapped the zip binary, before every plan/apply/destroy. Translating that directly meant an equivalent shell-based hook:

hooks:
  package:
    kind: command
    command: bash
    args: ["-c", "cd src && zip -r ../handler.zip . -x '*.test.js'"]
    events: [before.terraform.plan, before.terraform.apply, before.terraform.destroy]

Three problems with this, once you look past "it worked when I tested it":

• The invocation isn't even portable between macOS and Linux, let alone Windows. zip -x and tar --exclude take different glob syntax; BSD tar (what macOS ships) and GNU tar (most Linux CI images) disagree on flags like --exclude vs. -X excludefile. Two engineers on the same team can get different results running the "same" hook.
• Failures are opaque. A typo in a glob, a missing source directory — all of it surfaces as a shell exit code with no structure Atmos can validate ahead of time.
• The output isn't reproducible. Zip and tar both bake in each file's real modification time and permission bits. A fresh git clone sets every file's mtime to checkout time, and umask varies across machines and CI images — so identical source content produces a different archive on every rebuild. This is the same failure mode Terraform's own archive_file provider has been reported for over the years: two runs, same input, different checksum. Anything downstream that keys off the archive's hash — Lambda only redeploying when the zip's checksum changes, a build cache, a provenance check — sees a "change" that isn't one.

A data "archive_file" Terraform data source was tried first for the packaging step itself. It works fine when a config references the data source's own output attribute directly (output_path, output_base64sha256) — Terraform's graph orders that correctly. It broke here because the migrated module computed the zip path independently in a locals block, mirroring the original Terragrunt script's own variable, instead of referencing the data source's attribute — so there was no dependency edge forcing archive_file to run first. That's not a one-off: it's a documented class of bug, closed once the reporter switched to referencing the output attribute directly — the same fix this migration's module hadn't made. A before.terraform.* hook sidesteps the whole class of problem structurally — it runs and completes before Terraform's graph is even evaluated, so there's no reference to get wrong.

The Fix​

The new archive step type packages a directory or file into a zip, tar, or tgz archive using only Go's standard library — archive/zip, archive/tar, compress/gzip. No shelling out, so the same config produces the same archive structure everywhere Atmos runs:

steps:
  - name: package
    type: archive
    source: src/
    destination: handler.zip
    exclude:
      - "**/*.test.js"
      - "**/node_modules/**"

It has no dedicated hook kind — like every step type added since kind: step shipped, it reaches hooks through the same bridge, so it works as a lifecycle hook with zero extra plumbing:

hooks:
  package:
    kind: step
    type: archive
    events: [before.terraform.plan, before.terraform.apply, before.terraform.destroy]
    with:
      source: src/
      destination: handler.zip

How to Use It​

• source / destination — required. What to archive, and where to write it.
• format — zip, tar, tgz, tar.bz2, or tar.xz. Inferred from destination's extension when omitted (writing tar.bz2/tar.xz isn't implemented yet — see below).
• subpath — nests source's content under a path inside the archive, e.g. subpath: opt/nodejs for a Lambda Layer.
• include / exclude — glob filters, evaluated exclude-then-include.
• action — replace (default) always rebuilds the archive fresh from source. update adds/refreshes entries in an existing archive without touching the rest — supported for zip and uncompressed tar only, since tgz/tar.bz2/tar.xz compress the whole stream as one unit and can't be edited surgically. Selecting update on one of those formats fails with a clear error instead of silently falling back to a full rebuild.

create and extract are reserved in the schema for a future release, so it won't need a breaking change to add them later.

Reproducible Output​

A native step type fixes the shelling-out problems, but not the reproducibility one by itself — by default, entries still carry the source files' real mtime and permission bits (same as omitting the field, or setting it to filesystem explicitly). Set mtime: epoch or mtime: git to fix that too:

steps:
  - name: package
    type: archive
    source: src/
    destination: handler.zip
    mtime: epoch

mtime names the mechanism, not an outcome: it's the modification-time metadata stamped into each archive entry — not the source files on disk, and not the archive file's own OS-level mtime.

• filesystem — the default. Every entry carries the source file's real mtime and permission bits.
• epoch — every entry gets the same timestamp: the most recent Git commit that touched anything under source. One timestamp, whole archive. Named after the SOURCE_DATE_EPOCH reproducible-builds convention, which this mirrors conceptually — one shared reference timestamp for the whole build — even though the value here comes from Git history rather than an environment variable.
• git — each entry gets its own timestamp, from its most recent commit. Files with no Git history (build output, node_modules/) fall back to the same value epoch would use.

epoch and git both also normalize permission bits (0644, or 0755 if the source is executable), since inconsistent umask-derived permissions produce different archive bytes just as reliably as inconsistent timestamps do. Timestamps come from Git commit history via go-git — no shelling out to git log, and no dependency on SOURCE_DATE_EPOCH being threaded through every tool in the chain. Outside a Git repository, both modes fall back to a fixed reference date rather than failing the step. It's opt-in: existing workflows that don't set mtime see no change in behavior.

action: replace + mtime is idempotent — action: update is not. With replace, the same source produces the same bytes on every rerun, because replace always rebuilds from scratch. update doesn't get that guarantee even with mtime set: its existing entries keep whatever mtime/mode a prior write already gave them, and only the entries a given update call adds or refreshes get normalized — so the final bytes depend on the archive's history, not just source's current content. If you need the idempotent guarantee, use replace.

Get Involved​

See the archive step reference for the full field list, and the hooks reference for using it as a lifecycle hook. Questions or ideas? Join us in the Cloud Posse community Slack.

The Fix​

After Atmos installs and checksum-verifies a verifier binary, it now strips the macOS quarantine extended attributes (com.apple.quarantine, com.apple.provenance) and ad-hoc re-signs the binary — the same trick Homebrew uses for downloaded formula binaries. This only ever runs on binaries Atmos itself just downloaded into its own bootstrap path; a verifier already found on PATH is user-managed and already OS-trusted, so it's left untouched. On Linux and Windows, this is a no-op — only macOS re-validates trust on every exec.

How to Use It​

This is on by default (verifier_trust: auto) — most users won't need to touch it. To opt out entirely:

toolchain:
  verification:
    verifier_trust: disabled

See the toolchain verification docs for the full settings reference.

Get Involved​

Questions or feedback? Open an issue on GitHub or join the conversation in our community Slack.

The Fix​

atmos mcp add and atmos mcp remove manage mcp.servers in atmos.yaml directly — no YAML editing required. Two built-in presets skip the boilerplate entirely: self wires up Atmos's own MCP server, and atmos-pro wires up the Atmos Pro MCP server. Run atmos mcp add with no arguments at all and it defaults to atmos mcp add self, so the entire "let my AI assistant use Atmos" flow is one command.

On the other side, atmos mcp uninstall is the mirror image of the existing atmos mcp install — it removes servers from an AI client's config without touching atmos.yaml. add/remove manage the declarative source of truth; install/uninstall push and pull it to your client. They compose, but never step on each other.

atmos mcp list and atmos mcp status also now mention these commands directly instead of just saying "no servers configured," and nudge you to run atmos mcp add atmos-pro if Atmos Pro is already configured but its MCP server hasn't been added yet.

How to Use It​

# Let your AI assistant use Atmos's own tools -- writes mcp.servers.atmos,
# prompts to enable mcp.enabled if it's off, and installs into detected clients.
atmos mcp add self --install

# Add the Atmos Pro MCP server.
atmos mcp add atmos-pro

# Add an external server -- name and transport are inferred.
atmos mcp add "uvx awslabs.aws-documentation-mcp-server@latest"
atmos mcp add https://mcp.example.com/mcp --header "Authorization: Bearer ${TOKEN}"

# Remove a server, and uninstall it from wherever it was pushed.
atmos mcp remove aws-docs
atmos mcp uninstall aws-docs

See the MCP documentation for the full command reference and built-in preset details.

Get Involved​

Questions or feedback? Open an issue on GitHub or join the conversation in our community Slack.

The Problem​

ai.tools.enabled was designed for atmos ai chat/ask/exec — Atmos's own assistant deciding whether it's allowed to call tools during a conversation. atmos mcp start reused that same flag as a hard gate, even though the MCP server has nothing to do with Atmos's own chat loop: its only job is exposing Atmos tools to external clients like Claude Desktop or Cursor. mcp.enabled: true was already the explicit, purpose-built opt-in for that — requiring a second, differently-named flag on top of it just to get a non-empty server was pure friction, not safety.

The Fix​

atmos mcp start no longer checks ai.tools.enabled at all. Once mcp.enabled: true, tools register unconditionally — ai.tools.enabled now only governs atmos ai chat/ask/exec's own tool-use loop, which is what it was always meant for.

While in there, we also renamed three related settings for consistency. They're already nested under tools:, so the _tools suffix was redundant:

tools.allowed also picked up a second job. Previously it only skipped the confirmation prompt — every tool was still registered and callable, just some needed a "yes" first. Now, when non-empty, it also controls which tools exist at all: unlisted tools aren't registered, aren't visible in tools/list, and aren't offered to the AI. An empty or unset list still means "everything is registered, subject to normal confirmation rules" — unchanged.

How to Use It​

mcp:
  enabled: true

ai:
  enabled: true
  tools:
    # Optional -- omit entirely for a fully-populated MCP server.
    # When set, ONLY these are registered, and they skip confirmation:
    allowed:
      - atmos_describe_*
      - atmos_list_*
    blocked:
      - execute_bash_command

atmos mcp start

No ai.tools.enabled required.

Breaking Change​

tools.allowed_tools, tools.restricted_tools, and tools.blocked_tools are no longer read — there's no fallback or deprecation warning, just the new names. If your atmos.yaml sets any of these under ai.tools, rename them before upgrading. If you were relying on allowed_tools to skip confirmation for a subset of tools while still allowing everything else to run with a prompt, note the semantics changed: an unlisted tool is no longer registered at all. Move it to an empty allowed (or drop the list) and lean on restricted/blocked instead.

See AI Tools Configuration for the full reference.

Tags and labels give components that organizational context directly — components get both; auth identities and providers get tags — so you can select and act on infrastructure by what it is instead of by where you filed it.

The Problem​

A hierarchy can only organize infrastructure one way, but you need to operate on it along lines that hierarchy doesn't capture:

• A component's path describes its place in the tree, not what it is. It tells you the org, account, and region; it says nothing about tier, ownership, or compliance scope — and those apply across stacks and component types, not within one branch.
• That context ended up living outside the system instead of on the resource. A --query expression like .settings.tier == "network" encoded "tier-1" for one command; a hand-maintained --components list encoded it for another. Neither traveled with the component, and both went stale the moment something changed.
• The same gap showed up wherever Atmos manages many things. Components across every type (Terraform, Kubernetes, Helm, containers), plus auth identities and providers, all needed a way to carry their own organizational context instead of relying on someone remembering it.

The Fix​

Atmos now carries that organizational context as metadata, in two shapes:

• Tags — a simple list of words, for basic categorical membership. Filtering matches any of the given tags.
• Labels — a set of key-value pairs, for richer metadata. Filtering requires all of the given key=value pairs, the same semantics as a Kubernetes label selector.

components:
  terraform:
    vpc:
      metadata:
        tags: [production, networking, tier-1]
        labels:
          cost-center: platform
          compliance: sox

auth:
  providers:
    sso-prod:
      kind: aws/iam-identity-center
      start_url: https://my-org.awsapps.com/start
      tags: [production, aws, sso]

  identities:
    prod-admin:
      kind: aws/permission-set
      via:
        provider: sso-prod
      principal:
        name: AdministratorAccess
        account: {name: production}
      tags: [admin, production, elevated-access]

How to Use It​

Listing and filtering components:

atmos list components --tags production,tier-1
atmos list components --labels cost-center=platform,compliance=sox

Bulk operations — --tags/--labels compose with --all/--affected everywhere Atmos already supports bulk selection, across every component type:

atmos terraform apply --affected --tags production
atmos kubernetes apply --all --labels cost-center=platform
atmos helm apply --affected --tags production
atmos container up --all --tags production

Because this lives in the shared component registry (pkg/component), any component type — built-in or custom — that adopts the standard bulk-execution pattern gets --tags/--labels filtering automatically, with no per-type code.

The same filtering works for auth, since providers and identities are tagged the same way:

atmos auth list --tags production
atmos auth login --tags admin,production   # auto-selects if exactly one match, else prompts
atmos auth logout --tags production        # logs out every matching provider

Bridging into your modules — four new YAML functions read a component's own metadata.tags/metadata.labels without the usual !template/toJson boilerplate: !tags and !labels return the values directly, and !labels.keys/!labels.values return just the label map's keys or values. The most common use is feeding metadata.labels into the var.tags a terraform-null-label-style module expects (Terraform and AWS call a map "tags"; Atmos calls it a "label" — same data, different name):

components:
  terraform:
    vpc:
      metadata:
        labels:
          Namespace: eg
          Environment: prod
      vars:
        tags: !labels   # var.tags (map) <- metadata.labels

Get Involved​

Tags and labels are supported today on components across Terraform, Kubernetes, Helm, and container components; auth identities and providers support tags. Auto-discovering tags/labels from cloud provider metadata (for example, mapping AWS SSO PermissionSet tags into Atmos labels automatically) is a natural next step — if that's something you need, open an issue and let us know your use case.

The Problem​

Every vendored component in vendor.yaml pins a version, but nothing checked whether a newer one was available or what it would change. Bumping a version meant three separate manual steps: check upstream tags yourself, clone the repo somewhere to diff two versions, then edit the version field by hand — risking a stripped comment or a mangled anchor, since most YAML tools rewrite the whole file to make one change.

The Fix​

Two new commands close that loop, both built on Atmos's format-preserving pkg/yaml engine (the same one behind atmos config|stack|vendor get|set|delete):

• atmos vendor update checks every Git-backed source in vendor.yaml for a newer version — honoring each source's constraints (semver range, excluded versions, no_prereleases) — and writes the new version in place, preserving comments, anchors, and {{.Version}} templates. --check previews updates without writing anything; --pull runs atmos vendor pull immediately after.
• atmos vendor diff shows the Git diff between two versions (tags, branches, or commits) of a component, with no local checkout — it clones to a temp directory and cleans up after itself.

Both commands also work for components vendored purely through a per-component component.yaml instead of a repo-level vendor.yaml, falling back to it the same way atmos vendor pull already does (vendor.yaml wins if it declares the component). A repo with no vendor.yaml at all gets this for free; --component-manifests runs the same sweep alongside an existing vendor.yaml for repos that mix both styles, and component.yaml sources can declare their own constraints, matching vendor.yaml.

How to Use It​

# Dry run: show what would update, without touching any files.
atmos vendor update --check

# Update one component, or everything tagged 'networking'.
atmos vendor update --component vpc
atmos vendor update --tags networking

# Update and immediately pull the new versions.
atmos vendor update --pull

# Diff the current pinned version against the latest tag.
atmos vendor diff --component vpc

# Diff two specific versions, restricted to one file.
atmos vendor diff -c vpc --from 1.0.0 --to 2.0.0 --diff-file variables.tf

# Works with component.yaml-only vendoring too — no vendor.yaml required.
atmos vendor update --component vpc --check
atmos vendor diff --component vpc --type helmfile

Also Fixed: vendor.base_path and --chdir​

atmos --chdir=<dir> vendor update --check (and diff/get/set) failed with "No vendor.yaml found in the current directory" whenever <dir>'s atmos.yaml configured vendor.base_path to anything other than a literal ./vendor.yaml — common in infra-live-style repos. Vendor-wide discovery only checked the process's working directory and ignored atmos.yaml entirely. All four commands now resolve vendor.base_path (and ATMOS_VENDOR_BASE_PATH) the same way atmos vendor pull already does.

Get Involved​

See the vendor diff and vendor update docs for the full flag reference, or open an issue if you hit a vendoring setup this doesn't cover yet.

Interactive steps now fall back to their default value when there is no TTY, so the same workflow runs unattended in CI — no duplicate variant required.

The Problem​

Interactive step types (choose, input, confirm, filter, file, write) need a terminal to prompt you. In CI there is no TTY, so every one of them failed hard with interactive terminal required for step. The usual workaround was to fork your automation: an interactive version for humans and a flag-driven version for pipelines.

The Fix​

When an interactive step has a default and there is no TTY, Atmos now uses that default instead of erroring. With a TTY it still prompts (using the default as the pre-selected value). Without a default, the existing error stands — so you never silently deploy an unintended value.

workflows:
  build-manifests:
    steps:
      - name: account
        type: choose
        prompt: "Account"
        options: [dev, prod]
        default: !env STACK_ACCOUNT dev
      - name: tag
        type: input
        prompt: "Release tag"
        default: !env RELEASE_TAG latest
      - type: shell
        command: atmos kube build "{{ .steps.account.value }}/tao" --tag "{{ .steps.tag.value }}"

Locally, this prompts. In CI, it reads STACK_ACCOUNT / RELEASE_TAG (falling back to dev / latest), then runs the shell step with the captured values.

Dynamic Defaults from the Environment​

Defaults can come from the environment with the !env function (!env VAR fallback) in a workflow step's default, prompt, options, and placeholder. !exec is supported too. Custom commands defined in atmos.yaml already resolved !env; workflows now do as well.

Consuming those captured values in later shell/atmos steps ({{ .steps.<name>.value }}) works thanks to a companion fix that brought workflow command templating to parity with custom command steps.

How to Use It​

• Give each interactive step a default so it can run unattended.
• Use !env VAR fallback to pull that default from the environment in CI.
• Leave default off when a human must choose — the step still errors in CI, by design.

The behavior is automatic based on TTY detection; there is no new flag to set. It applies to both workflows and custom commands, which share the same step engine.

Get Involved​

Try converting one of your prompt-driven workflows to run in CI by adding default values, and let us know how it goes in GitHub Discussions.

atmos cast render demo.cast --output=demo.gif
atmos cast render demo.cast --output=demo.html
atmos cast render demo.cast --output=demo.out --format=html

The render command turns a recording into a rendered artifact — here it's converted straight to a GIF:

Replaying a recording in the terminal with play reproduces it exactly as it was captured:

And any command can capture its own session as it runs with --cast, no separate recording step required:

What Changed​

The atmos cast command now has a render interface built around --output and --format. Atmos infers the format from common output extensions such as .gif, .mp4, .html, .ascii, .png, .jpg, and .jpeg, while --format handles custom output filenames.

The same recording and rendering engine is also available to workflow and custom command steps. That means a runbook can capture the exact terminal session it executes, then turn the recording into an artifact without a separate wrapper script.

Workflow-Friendly Captures​

Cast support is designed for repeatable automation:

• Terminal output is recorded through the shared Atmos execution paths.
• Final terminal state can be rendered as static text, HTML, or images.
• Animated outputs are available for demos and walkthroughs.
• Render options are explicit, so CI and local commands use the same interface.

This is useful when a workflow needs to publish a proof-of-run artifact, attach a terminal demo to documentation, or keep a reproducible recording of an interactive command.

Why It Matters​

Teams often rely on external tools and custom shell scripts to capture terminal demos. Bringing cast recording and rendering into Atmos makes those captures part of the same command and workflow system that runs the work.

The result is easier to automate, easier to review, and easier to reproduce.

Topic-specific help fixes that by making default help focused, while keeping usage examples, command flags, and the full reference one flag away.

What Changed​

Default --help now shows the command description, usage, examples, subcommands, and flags for that command. Atmos no longer dumps every inherited global flag by default, so command-specific options stay visible.

When you need a narrower or broader view, use a help topic:

atmos terraform plan --help=usage
atmos terraform plan --help=flags
atmos terraform plan --help=all

--help=usage shows just usage and examples. --help=flags shows command-specific flags, plus compatibility flags when Atmos forwards options to a native tool. --help=all restores the full reference view, including global flags.

Every default help page includes a short reminder:

Use --help=usage for examples or --help=all for all flags and full help.

Why It Matters​

• Less noise by default. Atmos still exposes global flags, but they no longer bury the flags that actually change the command you are reading about.
• Examples are one command away. Atmos already maintains usage snippets in markdown help files, and those snippets now have their own focused view.
• Full reference stays available. --help=all keeps the exhaustive output available for scripting, documentation, and deep inspection.

Try It​

Compare the focused and full views:

atmos terraform plan --help
atmos terraform plan --help=all

Use --help=usage when you only need examples, and --help=flags when you are checking command-specific options.

Here's the same idea applied to vendored component versions:

View the full example

The Problem​

Version pins are configuration, but nobody manages them like configuration:

• No source of truth. The same tool version is repeated across workflow YAML, Dockerfiles, stack manifests, and CI scripts. Environments drift silently because there is nothing to drift from.
• Bolt-on updaters don't understand your stacks. Renovate and Dependabot see files, not Atmos configuration. They can't resolve a version into a stack, don't know your tracks or environments, and produce PR noise you tune with regex managers instead of policy.
• Mutable tags are a supply-chain risk. actions/checkout@v4 and nginx:latest can change underneath you. Pinning to SHAs by hand is the fix everyone agrees on and nobody keeps up with.

The Fix​

The Atmos Version Tracker makes external versions first-class Atmos configuration. You declare a catalog under version: in atmos.yaml; Atmos owns resolution, locking, policy, and file rewriting:

version:
  track: prod

  dependencies:
    checkout:
      ecosystem: github-actions
      package: actions/checkout
      desired: v6
      update:
        pin: sha        # lock and render the immutable commit SHA

    opentofu:
      ecosystem: toolchain
      package: opentofu
      desired: "~1.10"

    nginx:
      ecosystem: oci
      package: library/nginx
      desired: "1.29.0"

  tracks:
    prod:
      dependencies:
        nginx:
          desired: "1.29.1"

  files:
    - manager: github-actions
      paths: [.github/workflows/*.yaml]
    - manager: marker
      paths: [Dockerfile]
    - manager: template
      paths: ["**/*.tmpl"]

Resolved versions land in a committed versions.lock.yaml, so local runs and CI are deterministic. Updates are policy-driven — strategy caps (major/minor/patch), cooldown windows (14d, 2w), include/exclude rules, and prerelease policy — and every version held back by policy is reported with the reason instead of silently skipped:

atmos version track update

In an interactive terminal this renders as a styled table. Use --format=csv or --format=tsv for delimited output; piped table output remains a table:

Track,Name,From,To,Updated,Reason
prod,checkout,v6.1.0,v6.2.0,true,
prod,nginx,1.29.0,,false,"1.30.0 released 3d ago; cooldown 14d has not elapsed"

File managers then rewrite your actual project files from the lock. Pinned entries get the immutable SHA with the human-readable version as a trailing comment — the same round-trip convention Renovate and Dependabot use:

- uses: actions/checkout@8edcb1bdb4e267140fa742c62e395cd74f332709 # v6.1.0

Any text file with comments can carry a managed version via a marker annotation:

# atmos:version opentofu
ENV TOFU_VERSION=1.10.6

And comment-hostile formats (like JSON) render from *.tmpl templates with the .version context. In stacks, !version name and {{ .version.name }} resolve from the lock, so versions stop being copy-pasted into stack manifests at all.

How to Use It​

Add an entry (the ecosystem is inferred from the package), lock, and apply:

atmos version track add checkout --package=actions/checkout --pin=sha
atmos version track lock      # resolve desired versions into versions.lock.yaml
atmos version track apply     # rewrite managed files from the lock

Then gate CI on the whole thing staying honest:

steps:
  - uses: actions/checkout@v6
  - run: atmos version track apply --check   # fail if any managed file is stale
  - run: atmos version track verify          # lock fresh AND files current

atmos version track status shows where you stand at any time — including newer-available (blocked) when a newer version exists upstream but your cooldown or strategy is deliberately holding it back. That's a passing state, not a failure: the locked version is exactly what your policy wants deployed.

See the atmos version track command reference and Managed Versions configuration for the full surface, or try the runnable examples/version-tracker example.

Get Involved​

If you've been stitching together Renovate configs to approximate this, we'd love to hear which datasources and ecosystems you need next. Open a discussion or issue in the Atmos repo, or join us in the Cloud Posse Slack.

What Changed​

Atmos validates explicit custom YAML tags during atmos.yaml and stack manifest processing. If a tag is not one of the supported Atmos YAML functions, Atmos returns an unsupported tag error that includes the valid options.

vars:
  home: !envv HOME

Instead of quietly accepting the misspelled !envv tag, Atmos reports that the tag is unsupported and points users toward valid functions like !env, !exec, !include, and the other supported YAML tags.

Exact Matching​

Validation uses exact tag matching. A misspelled function such as !envv no longer matches the supported !env prefix, which prevents typos from slipping through parser or resolver paths that previously checked only the beginning of a tag.

Standard YAML tags such as !!str continue to work normally.

Why It Matters​

YAML functions are often used for dynamic values: environment variables, Terraform outputs, secrets, Git metadata, and included files. A misspelled tag can otherwise hide until much later in a deployment workflow, where the failure is harder to connect to the original configuration.

Failing at parse or processing time makes the error immediate and actionable.

Get Started​

No configuration is required. Use the documented Atmos YAML functions as usual, and Atmos will report unsupported tags when it finds them.

atmos build --target linux

We replaced the old Make-based build and CI entrypoints with Atmos custom commands to improve the developer experience and dogfood our own workflow engine. Build and test workflows now expose the flags developers actually care about, such as the target platform, while Atmos owns the shell details, cross-compilation wiring, output paths, and CI glue behind the command.

What Changed​

The repository's development commands now live in .atmos.d/ command groups instead of Make targets. The root atmos.yaml stays focused on project configuration, while the command surface is split by concern:

• atmos build ... for dependencies, binaries, versions, and docs generation.
• atmos test plus mode flags for short, acceptance, coverage, and race-test workflows.
• atmos lint ... for changed-file linting, custom lintroller rules, go.mod checks, and link checks.
• atmos check ..., atmos format ..., and atmos cache ... for repository maintenance workflows.
• atmos screengrabs ... for website screengrab generation.

Makefiles remain only as migration guards. If someone runs an old target, the Makefile exits and points them to the Atmos command that replaced it.

A Cleaner Command Surface​

The result is intentionally plain. The repository now has command groups that read like the workflows contributors actually run:

atmos build deps
atmos build --target linux
atmos test acceptance --cover
atmos lint --changed
atmos screengrabs all

This keeps the developer contract narrow. The command can grow flags like --target without forcing every contributor or CI job to understand the lower-level build minutia. Atmos handles the parsing, defaults, and orchestration once, and every caller gets the same behavior.

Why It Matters​

This is dogfooding in the useful sense: Atmos exercises its own custom command engine for the daily loops that maintain Atmos. That gives contributors one command vocabulary locally and in CI, and it gives us immediate feedback when custom commands need to become better.

It also removes a layer. CI now calls grouped Atmos commands such as atmos build deps, atmos build --target linux, and atmos test acceptance --cover. The screengrab workflow calls atmos screengrabs all. The install script has its own Linux, macOS, and Windows smoke test, so the installer path gets exercised directly too.

Try the Pattern​

If you are maintaining a repo with an aging Makefile, .atmos.d/ is a good place to split the command surface by concern. Keep project configuration in atmos.yaml; keep operational commands in grouped files such as .atmos.d/build.yaml, .atmos.d/test.yaml, and .atmos.d/lint.yaml.

For the general command schema, see the custom commands documentation. For a smaller standalone example, browse the custom commands example.

What Changed​

Command help now groups native Atmos commands under BUILT-IN COMMANDS and commands defined in atmos.yaml under CUSTOM COMMANDS. Teams with project-specific runbooks can now see what Atmos provides out of the box and what their repository adds locally.

Error formatting also got cleaner. Explanations render as a styled callout when color is enabled, while hints stay as direct, actionable lines. The formatter reserves room for callout padding before wrapping text, so long explanations stay aligned instead of reflowing inside the box.

Why It Matters​

• Faster command discovery. Built-in commands and custom shortcuts no longer compete in one flat list.
• Cleaner troubleshooting. Error explanations are visually distinct from hints without adding extra section headers.
• More consistent output. Snapshot comparisons and stderr formatting now preserve intentional whitespace unless a test opts into trailing-whitespace tolerance.

Get Involved​

Run atmos --help or any command-specific --help page in a repository with custom commands to see the new grouping.

The summary includes the image reference, digest, image ID, OCI metadata, runtime configuration, environment variables, labels, layer digests, and the formatted raw inspect JSON. Push summaries use the pushed digest when the registry returns one, so reviewers can see the canonical artifact that was published.

ci:
  enabled: true
  summary:
    enabled: true

Summaries are best-effort. A successful build or push is not failed just because image inspection or job-summary writing is unavailable. When ci.summary.enabled: false is set, Atmos skips the image summary entirely.

This keeps native Atmos container pipelines self-contained: build, push, and review the image metadata from the same workflow or component command you already run locally.

The result is easier to read, easier to review, and keeps the same recursive merge behavior that existing custom commands rely on.

What Changed​

Before, command hierarchies had to be expressed as nested commands arrays:

commands:
  - name: casts
    commands:
      - name: generate
        commands:
          - name: examples
            commands:
              - name: custom-commands
                commands:
                  - name: hello-greet
                    description: Regenerate the Custom Commands example cast
                    steps:
                      - type: shell
                        command: atmos casts setup

That shape is programmatically consistent, but it is not very friendly when the nesting only exists to spell out the command path.

Now you can write the same command as:

commands:
  - name: casts generate examples custom-commands hello-greet
    description: Regenerate the Custom Commands example cast
    steps:
      - type: shell
        command: atmos casts setup

Atmos expands the path-based name into the normal recursive command tree before merging configuration.

Merge Behavior Is Preserved​

This is syntax sugar, not a new command model. A command named casts generate demo is normalized to the same internal structure as:

commands:
  - name: casts
    commands:
      - name: generate
        commands:
          - name: demo

Because normalization happens before config merge and unmarshal, later configs and imports still override matching command fields by segment name. Nested commands arrays still merge recursively, and sibling commands that share a prefix still collapse into one command tree.

That means you can define a shared branch in one config:

commands:
  - name: casts generate
    description: Generate casts

And add leaves elsewhere:

commands:
  - name: casts generate examples sops-secrets secret-lifecycle
    description: Regenerate the SOPS secrets example cast

Atmos treats both definitions as part of the same casts -> generate command branch.

When to Use It​

Use path-based names when the intermediate command levels do not carry their own behavior. This is ideal for demo generation, validation commands, and operational command groups where the path is the structure.

Keep the nested form when an intermediate command needs its own description, flags, environment, steps, or child-specific organization that is clearer when written explicitly.

Both forms can coexist. The important rule is simple: spaces in commands[].name are treated as command path separators, so literal spaces inside one command segment are not supported.

That is the point of this update: the docs now have short terminal casts for the parts of Atmos that are easier to understand by watching them run.

No big setup. No long pitch before the useful part. Open a page, press play, and see what happens.

New Recordings​

The first set covers the runs people usually want to inspect first:

• plan
• deploy
• output
• source pull
• stack list
• component details
• stack details
• local AWS demo

Each cast is meant to answer the same question: what will I see when I run this?

Plan, Deploy, Output​

The plan cast starts the set. The next two show the follow-up runs:

Together, they show the basic path from preview to apply to result.

Source Pull​

This cast shows the source pull by itself:

It is intentionally plain. You can see what is fetched and what the terminal prints when it finishes.

Look Around First​

Sometimes the next step is to inspect the project before changing anything.

These casts show what Atmos sees before you ask it to do anything else.

Local AWS Demo​

The longest cast shows a full local AWS run:

It brings the local service up, waits for it, runs against it, prints the result, and shuts it down.

Kept Current​

The recordings are made by Atmos:

github.com/cloudposse/atmos/blob/main/demo/casts/atmos.yaml

That file builds the binary, prepares the demo files, records the casts, copies them into the website, and checks the result.

The docs get a visible example. The repo gets a repeatable way to refresh it.

The Problem​

When a run fails, the important question is usually not "what did the terminal print?" It is "what command ran, with which arguments, from which directory, for how long, and how did it exit?"

Humans can sometimes reconstruct that from logs. Agents and support tooling should not have to scrape terminal prose to find the root cause.

The Change​

Atmos now supports an opt-in diagnostics stream: machine-readable JSONL events written to a file.

diagnostics:
  enabled: true
  file: .atmos/diagnostics.jsonl
  include_output: false

The same settings can be controlled with environment variables:

ATMOS_DIAGNOSTICS_ENABLED=true \
ATMOS_DIAGNOSTICS_FILE=.atmos/diagnostics.jsonl \
atmos terraform plan vpc -s plat-ue2-dev

Because the output is JSONL, it is easy to inspect with tools like jq:

jq 'select(.type == "process.exit")' .atmos/diagnostics.jsonl

Diagnostics vs. Logging​

Logs are human-readable status and narrative output. They explain what Atmos is doing for someone watching the run.

Diagnostics are machine-readable event records for tooling, agents, and post-run inspection. They are designed to accelerate root-cause analysis by giving agents structured facts about subprocesses, exits, durations, cancellation, and failures without requiring them to parse terminal output.

diagnostics.include_output can include masked subprocess stdout and stderr chunks, but it is disabled by default. Diagnostic output is masked before it is written.

Why It Matters​

• Agentic troubleshooting gets faster. Agents can reason from structured events, identify the failing step, and move from diagnosis to remediation.
• CI artifacts become more useful. Save the JSONL file with a failed job and inspect it after the terminal session is gone.
• Logs stay for people. Diagnostics add a tooling-oriented layer without replacing human-readable logs.

Get Involved​

Enable diagnostics when you need a structured troubleshooting artifact, especially for CI and agent-driven workflows.

The Problem​

Many teams keep authentication, identity, terminal, and CI defaults in a central infrastructure repository. That works well for governance, but it creates friction for workload or app repositories: every repo needs the same profile definitions, and every update has to be copied everywhere.

That duplication is especially painful for auth profiles. The central platform team owns the provider and identity shape, while each app repository only wants to consume the right profile and add a small local override.

The Change​

Profile config files can now use import:, including remote imports. That means a profile in a workload or app repository can pull shared configuration from a central repository and then override only the local pieces it owns.

import:
  - "github.com/my-org/platform-atmos//profiles/shared-auth.yaml?ref=v1.4.0"

logs:
  level: Debug

settings:
  terminal:
    max_width: 140

The imported file provides the baseline. Values in the local profile are merged over it, so the workload repository can keep its local preferences without forking the shared auth profile.

Why It Matters​

• Centralize auth profiles. Platform teams can publish shared provider and identity configuration once.
• Keep app repos small. Workload or app repositories can consume the shared profile instead of duplicating it.
• Override locally when needed. Imported profile configuration is still just layered Atmos configuration, so local profile values win.

Get Involved​

See the profiles documentation for profile discovery, activation, and merge behavior.