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

track: prod
results:
  - name: checkout
    from: v6.1.0
    to: v6.2.0
    updated: true
  - name: nginx
    from: 1.29.0
    updated: false
    reason: "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.

Atmos aliases can now encode those defaults directly. They behave more like shell aliases: rewrite argv prefixes before command parsing, and match full command paths, including subcommands.

What Changed​

The aliases section is now the single interface for shortcuts and command defaults. Alias keys and values are parsed like shell fields, the longest matching command path wins, and expansion happens before flag normalization.

That means a short alias can still point at a command:

aliases:
  tp: terraform plan

And when a default flag belongs to a command or subcommand, the alias can define that too:

aliases:
  terraform: terraform --identity=false
  "terraform apply": terraform apply -auto-approve
  "describe component": describe component --process-functions=false

Running atmos terraform apply app -s dev expands the command path first, then passes the remaining arguments through normal command and flag handling.

Why It Matters​

• One configuration surface. Aliases now cover both shortcuts and command defaults without a separate args section.
• Subcommands work naturally. Multi-word aliases such as "terraform apply" can add behavior to one command path without affecting siblings like terraform plan.
• User flags still win. Defaults injected by an alias appear earlier in argv, so explicit flags typed by the user later on the command line can override them.

Get Involved​

See the aliases configuration reference for examples of shortcuts, same-name aliases, command-path aliases, and quoting rules.

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.

The Problem​

Shell checks work until they have to be portable, readable, and friendly. A workflow might need vhs, ffmpeg, a generated config file, and a local output directory before the real work starts. Encoding that as inline shell makes the workflow harder to scan and usually produces a poor error when something is missing.

The Change​

Atmos now has a declarative require step type for workflow and custom command prerequisites. The assert step type is an alias for the same behavior.

steps:
  - name: require recording tools
    type: require
    tools:
      - vhs
      - ffmpeg
    files:
      - ./Taskfile.yml
    dirs:
      - ./demo
    hint: "on macOS run: brew install vhs ffmpeg"

The step checks that tools are executable on PATH, files exist, and directories exist. If anything is missing, Atmos fails fast with one aggregated error and the remediation hint.

Why It Matters​

• Prerequisites are visible. The workflow declares what it needs before the work starts.
• Errors are actionable. Missing tools and paths are reported together with a hint.
• It is read-only. require never installs tools and never mutates PATH; use dependencies.tools when you want Atmos to manage tool installation.

Get Involved​

See the require step reference for all supported fields and examples.

The Problem​

Some Atmos commands produce rich, multi-line output that is useful in a real terminal but awkward in demos, docs, and recorded walkthroughs. When everything appears at once, important transitions are easy to miss.

That is especially noticeable with VHS recordings and scripted demos, where readable pacing matters as much as the final output.

The Change​

Atmos now supports settings.terminal.speed, also available as ATMOS_TERMINAL_SPEED, to pace terminal output by lines per second.

settings:
  terminal:
    speed: 18

ATMOS_TERMINAL_SPEED=18 atmos describe stacks

A value of 0 keeps the existing unlimited output behavior. That is the default, so normal interactive and CI usage does not change unless you opt in.

Why It Matters​

• Better recordings. Output appears at a readable pace for demos, tutorials, and screengrabs.
• No command rewrites. Keep the same Atmos command and control pacing through config or an environment variable.
• Default behavior is unchanged. Unlimited output remains the default.

Get Involved​

See the terminal settings documentation for the full terminal configuration reference.

Atmos now folds each workflow and custom-command step into its own collapsible, named log group. You see the list of steps up front and expand only the one you care about.

The Problem​

Workflows and custom commands run a sequence of steps, and in CI all of that output landed in one flat log. The CI provider had no idea where one step stopped and the next started, so it couldn't help you navigate. The usual fix is to hand-write echo "::group::..." around each run: step — but Atmos steps aren't run: steps you control line by line, so there was no clean place to put those markers. You scrolled.

The Fix​

Atmos now folds its output into the active CI provider's log groups. On GitHub Actions that's the ::group:: / ::endgroup:: workflow commands, so the run log renders as a list of expandable sections instead of a wall of text. A single ci.groups.mode picks the granularity — and because CI providers can't nest groups, the mode is the one knob you need:

• auto (default) — the finest grouping per command. A workflow renders one group per step; a direct atmos terraform plan renders one group per phase (init, then plan):

  ▸ deploy network          ▸ terraform init
  ▾ deploy cluster          ▾ terraform plan
    atmos terraform apply…    ... the plan you actually want ...
  ▸ smoke test
  

• invocation — one group around each whole atmos <command> run, including bare commands you invoke directly from CI YAML.

• off — no grouping.

A step that runs atmos terraform apply is one group, not three — the outermost group always wins. You write nothing extra: no markers in your workflows, custom commands, or CI YAML.

How to Use It​

It rides on the existing ci configuration. Turn on CI integration and grouping defaults to auto:

ci:
  enabled: true   # master switch
  groups:
    mode: auto    # auto | invocation | off  (default: auto)

Grouping is emitted only when both ci.enabled is true and a grouping-capable CI provider is detected (GitHub Actions). Outside CI it's a complete no-op, so local runs look exactly as before. You can also set it per-run with ATMOS_CI_GROUPS_MODE.

A couple of details keep it unobtrusive:

• No nested groups. When a command invokes atmos again (a custom command calling another, a nested workflow, or a workflow step running atmos terraform apply), the child detects the open group and stays flat — you always get one level of grouping.
• Secret-safe labels. Group labels go through the same masking layer as the rest of Atmos output, so a secret resolved into a step command or flag can't leak into the label.

See the ci.groups reference for the full configuration.

Get Involved​

Atmos is open source and we'd love your feedback. Join the conversation in the Cloud Posse community or open an issue on GitHub.

What Changed​

kind: step runs one registered step type as a lifecycle hook. kind: steps runs several registered step types in order:

hooks:
  test-fixtures-up:
    events: [before.terraform.test]
    kind: steps
    on_failure: fail
    with:
      - type: emulator
        component: aws
        stack: fixtures
        action: up

      - type: atmos
        command: terraform apply vpc -s fixtures -auto-approve

The hook envelope stays the same: events, when, on_failure, retry, and env are still hook-level controls. The ordered payload lives under with:, the same conventional payload key used by kind: step.

Why This Matters​

Some test fixtures need real lifecycle ordering. For example, a component test may need a local AWS emulator before it can provision a VPC fixture, and the fixture must be destroyed after the test even if the test fails.

Before kind: steps, the choices were awkward:

• split the lifecycle across multiple hooks and rely on unordered map iteration,
• move component-specific fixture setup into a custom command or workflow, or
• fall back to a helper script.

kind: steps keeps the fixture lifecycle declarative and component-local:

hooks:
  test-fixtures-up:
    events: [before.terraform.test]
    kind: steps
    on_failure: fail
    with:
      - type: emulator
        component: aws
        stack: fixtures
        action: up
      - type: atmos
        command: terraform apply vpc -s fixtures -auto-approve

  test-fixtures-down:
    events: [after.terraform.test]
    when: always
    kind: steps
    with:
      - type: atmos
        command: terraform destroy vpc -s fixtures -auto-approve
      - type: emulator
        component: aws
        stack: fixtures
        action: down

Steps run in list order. If a step fails, Atmos stops the list and applies the hook's on_failure policy. A hook-level retry retries the whole ordered list.

For Terraform tests, Atmos still owns the normal component preparation. It generates the tested component varfile from the selected stack and can pass a second generated test varfile from test.vars. Because test.vars resolves after before.terraform.test hooks run, it can use !terraform.state to pass fixture outputs into Terraform test without scripts.

Learn More​

See the Hooks reference for the full kind: steps syntax.

What Changed​

Two things came together:

1. Flags are now template variables. When a custom command declares flags, each one is exposed to its steps as {{ .Flags.<name> }}. Step titles, shell commands, working directories, and table data all resolve those values.
2. table steps are fully templated. A table step's title, columns, and every cell in data are rendered as Go templates, so the table content can depend on flags and other step variables.

How to Use It​

Here's a real example now shipping in examples/demo-stacks — a platform command group whose subcommands take a --stack flag and build their output from it:

commands:
  - name: platform
    description: Platform team shortcuts for stack discovery and day-two commands.
    commands:
      - name: status
        description: Show stacks, components, and common next actions for one stack.
        flags:
          - name: stack
            shorthand: s
            description: Target stack.
            required: true
        steps:
          - type: stage
            title: Components in {{ .Flags.stack }}
          - type: shell
            command: atmos list components -s {{ .Flags.stack }}
          - type: table
            title: Platform commands
            columns:
              - task
              - command
            data:
              - task: Show variables
                command: atmos list vars myapp -s {{ .Flags.stack }}
              - task: Plan affected
                command: atmos terraform plan --affected

Run it like any other command:

atmos platform status -s plat-ue2-dev

Every {{ .Flags.stack }} resolves to plat-ue2-dev, the stage titles and table rows fill in, and the shell steps run against the right stack.

View the full example

Why It Matters​

• Build your own shortcuts. Wrap your team's day-two operations — discovery, planning, secret access — into named commands that adapt to their flags.
• Rich output without scripts. Tables, staged sections, and dynamic titles are declared in YAML, not hand-rolled in bash with printf and column.
• Consistent across workflows and custom commands. The same step library powers both, so what you learn in one applies to the other.

Get Involved​

See the workflow step types and the table step reference to start building. Share what you create with the Atmos community.

The Problem​

As infrastructure grows, the relationships between components matter as much as the components themselves. A vpc is a prerequisite for the eks cluster, which is a prerequisite for the alb-controller, and so on. Until now, answering "what would break if I change this?" or "what has to exist before I deploy that?" meant reading atmos describe dependents for one component at a time and stitching the picture together in your head.

The Solution​

atmos list dependencies gives you the whole graph at a glance, as a tree:

atmos list dependencies

Tree output keeps stack context next to the component hierarchy, with component type as secondary metadata on the right:

Dependencies
Stack         Component                 Type
plat-ue2-dev  app-config                terraform
              ├──depends on ↓
              │  ├──▶ dynamodb-table
              │  └──▶ kms-key
              └──required by ↑
                 └──(none)

Triangle markers show edge direction: ▶ means the component depends on that child, and ◀ means that child depends on the selected component.

By default it walks every component and renders both directions — prerequisites and dependents. Scope it to a stack, focus on a single component, pick a direction, or emit structured data instead:

# Limit to one stack
atmos list dependencies --stack plat-ue2-dev

# Focus on a single component in a stack
atmos list dependencies vpc --stack plat-ue2-dev

# Only what the component depends on (its prerequisites)
atmos list dependencies vpc --stack plat-ue2-dev --direction forward

# Only what depends on the component (its dependents)
atmos list dependencies vpc --stack plat-ue2-dev --direction reverse

# Machine-readable output for scripts and CI
atmos list dependencies --format json

Why It Matters​

• See blast radius before you change anything. --direction reverse answers "what depends on this?" so you know what a change could affect.
• Understand deployment order. --direction forward shows prerequisites, so you know what must exist first.
• Consistent with the rest of Atmos. Dependencies come from the same dependencies.components / settings.depends_on sources used by atmos describe dependents, so the tree never contradicts your CI change-detection.

Get Involved​

See the atmos list dependencies reference for all flags and output formats. As always, feedback and ideas are welcome in the Atmos community.