The Problem​

The net.CIDRSubnets and net.CIDRHost functions calculate subnet CIDRs and host IP addresses from each environment's parent CIDR, reducing hardcoded addresses across stacks. Both functions require Gomplate's experimental mode, but Atmos previously provided no option to enable it in stack templates.

The Fix​

The Gomplate configuration now includes an experimental option for enabling experimental functions in stack templates. It defaults to false and can be set globally or overridden per stack.

Import templates use the global value from atmos.yaml. The option does not apply to document generation or scaffold templates.

How to Use It​

Enable experimental Gomplate functions in your project configuration:

templates:
  settings:
    enabled: true
    gomplate:
      enabled: true
      experimental: true

Calculate Subnet CIDRs and Host IP Addresses​

The following stack derives subnet CIDRs and a host IP address from one parent CIDR. It assumes a Terraform component named network with cidr_block, subnet_cidrs, and service_ip inputs:

vars:
  stage: dev

components:
  terraform:
    network:
      vars:
        cidr_block: "10.42.0.0/16"
        subnet_cidrs:
          - "{{ index (net.CIDRSubnets 2 .vars.cidr_block) 0 }}"
          - "{{ index (net.CIDRSubnets 2 .vars.cidr_block) 1 }}"
        service_ip: "{{ net.CIDRHost 10 (index (net.CIDRSubnets 2 .vars.cidr_block) 1) }}"

The call to net.CIDRSubnets 2 adds two prefix bits, splitting the /16 into four /18 subnets. The zero-based index calls select the first two subnets. net.CIDRHost 10 calculates the address at offset 10 in the second subnet. The network inputs resolve to:

cidr_block: 10.42.0.0/16
subnet_cidrs:
  - 10.42.0.0/18
  - 10.42.64.0/18
service_ip: 10.42.64.10

Override per Stack​

To disable experimental functions for a stack while keeping them enabled globally:

settings:
  templates:
    settings:
      gomplate:
        experimental: false

Stacks inherit the global value when this option is omitted. An explicit false disables experimental functions for that stack, even when they are enabled globally.

Get Involved​

For questions or feedback, please open a GitHub issue.

Try it out​

atmos init examples/policies
cd policies

atmos policy check
atmos policy test tests/cases.json

How it works​

Each quick start opens on the example tab, with copyable commands to initialize a complete project and try the feature. The Install Atmos tab is there when you need it. Related examples share one installation tab and have their own named tabs.

Policy validation output​

The policy check command now shows a readable summary on stderr. Scripts consuming its previous JSON output must use atmos policy check --format json, which preserves the valid, rules, and hooks fields on stdout.

Get Involved​

Tell us which examples would help you in GitHub Discussions.

The Problem​

Top-level CLI-config imports - the import: list in atmos.yaml and the auto-discovered .atmos.d fragments - were a plain list of strings, and every entry was implicitly optional. If an import could not be resolved or merged, Atmos logged a warning and kept going. That is the right default for a nice-to-have overlay, but it is exactly wrong for a fragment that constrains behavior - for example, a read-only tool allowlist that limits what the Atmos MCP server is permitted to do. A silent failure there leaves the tool running without its guardrail.

The string-only model also left no room to express intent: no way to mark an import required, no way to scope an import to workstations versus CI, and no signal when a remote import was pinned to a mutable ref. The usual workaround for the CI problem was to keep the fragment out of the committed config entirely - gitignored behind a *.yaml.example template that nobody could actually use.

The Fix​

Each entry in the import: list now accepts an object form alongside the familiar string form, bringing CLI-config imports toward parity with the object model that stack-manifest imports already have. The two forms mix freely, and string entries behave exactly as before.

import:
  # String form: OPTIONAL (fail open) - a failed import is warned and skipped. Unchanged.
  - "configs.d/base-settings.yaml"

  # Object form: REQUIRED by default (fail closed) - a failed import aborts the load.
  - path: "git::https://github.com/acme/shared-config.git//.atmos.d/mcp.yaml?ref=v1.2.3"
    skip_if_missing: false

  # Conditional: resolve on workstations, skip in CI.
  - path: "configs.d/local-tooling.yaml"
    when: local

This closes four gaps at once:

• Optional vs required. A string entry stays optional (warn and skip). An object entry is required by default - a failed resolve or merge aborts configuration loading. Set skip_if_missing: true to opt an object entry back into warn-and-skip. Make the fragment that matters fail closed, so a missing or malformed guardrail stops the run instead of silently disappearing.
• Conditional loading. A per-import when: local or when: ci condition decides whether the import is resolved at all. Developer-tooling config stays committed and active for developers while auto-skipping in CI, so an automated apply never resolves a cross-repo remote import - no gitignore/.example workaround required. For anything beyond local-vs-CI, when also accepts a CEL expression - authored as a quoted "!cel ..." string - that can read the process environment through the env map, so an import can be gated on any variable you set.
• Optional MCP servers. A server in a shared mcp.servers config can set optional: true. When its identity cannot be resolved in the active auth context - for example a central-logging reader that only some repos define - Atmos skips that server with a warning instead of failing the others.
• Pin warnings. Atmos now warns when a git:: import is pinned to a mutable ref (a branch, or no ?ref= at all), recommending a commit SHA or version tag - the config-import analogue of catching an unpinned GitHub Action at author time.

Everything here is additive. String entries, servers without optional, and unpinned imports all behave exactly as they did before - the pin check is a warning, not an error.

How to Use It​

Mark a security-bearing fragment required, and scope a developer-tooling fragment to local:

import:
  - path: "git::https://github.com/acme/shared-config.git//.atmos.d/mcp.yaml?ref=v1.2.3"
    skip_if_missing: false                   # must load, or the run stops
  - path: "git::https://github.com/acme/shared-config.git//.atmos.d/ai.yaml?ref=v1.2.3"
    when: local                              # workstations only
  - path: "configs.d/prod-overrides.yaml"
    when: '!cel env.DEPLOY_ENV == "prod"'    # dynamic: only when DEPLOY_ENV=prod

Share one MCP config across repos that do not all define the same identities:

mcp:
  servers:
    central-logs:
      command: uvx
      args: ["awslabs.cloudwatch-mcp-server@latest"]
      identity: "central-logging"   # defined only in some consumer repos
      optional: true                # skip with a warning where unavailable

A runnable walkthrough lives in the cli-config-imports example, including how to see conditional loading differ between a workstation and CI, and how a required import fails closed.

Try it out​

atmos init examples/cli-config-imports
cd cli-config-imports

atmos describe config --format yaml

Get Involved​

This landed from issue #3430. If you share CLI config across repositories, try the object form and let us know what else should reach parity with stack imports - open an issue or start a discussion on GitHub.

The recording creates and builds the Go starter, validates its exported capabilities, publishes it to an ephemeral local OCI registry, then lists the configured discovery source, demonstrates explicit JSON output, searches for and installs the release, and inspects the installed plugin. It runs the installed command and repeats the OIDC conformance suite against the downloaded executable, then searches the cached index after stopping the registry. Authentication uses local mock issuer and credential broker endpoints; it does not contact a customer's identity provider or publish to an external registry.

The Problem​

Custom authentication usually includes more than obtaining a token: browser interaction, verification, credential exchange, secure caching, refresh, and logout all need to work together. A team should be able to own its provider-specific behavior while continuing to use Atmos identities and credential chains.

The Fix​

The experimental plugin commands provide scaffolding, testing, OCI distribution, explicit installation, and locked restoration. The Go OIDC starter includes browser login with PKCE, verified tokens, an access-token exchange for temporary AWS credentials, cached reuse, refresh, and logout. Its broker identity can feed a built-in AWS assume-role identity.

The generated conformance suite runs against local mock endpoints. Live integration steps are explicit and separate, so a passing mock test is never presented as evidence that a customer's issuer has been validated.

Plugin policies let organizations restrict registries and approve specific packages using CEL or Starlark. The same rules apply to installation and cached activation, alongside signature and trusted publisher requirements.

How to Use It​

Start with the plugin scaffold, build it, and run its fixtures:

atmos plugin create ./corporate-oidc --kind acme/oidc --module example.com/acme/oidc --defaults
cd corporate-oidc
atmos build
atmos test
atmos dev registry up
atmos push

The scaffold includes these custom commands in atmos.yaml, plus a local OCI emulator and repository discovery configuration. Search builds and caches an index from repository metadata; plugin releases publish independently. Optional catalogs provide curated snapshots for larger collections and can be scoped to products or teams. Local pushes require Docker but no registry credentials. Stop the ephemeral registry with atmos dev registry down. Use atmos push --to <repository> for a remote destination; configure its identity and run atmos auth login --identity publisher when authentication is required.

Follow the generated README to register a native application with your issuer and configure the broker contract. To try the build in a consumer project, point the package at the plugin directory with path in a profile of your own. Any profile name works, and the committed configuration and lock keep describing the release:

plugins:
  packages:
    corporate:
      path: /absolute/path/to/corporate-oidc

atmos --profile=my-local-build plugin run corporate --
atmos --profile=my-local-build auth login --identity broker

A package with path runs the directory in place: nothing is fetched, locked, or checked for a signature, and Atmos warns each time it starts the plugin. Rebuild and the next command runs the new executable, with no reinstall. Without the profile, the same project uses the release. The plugin development tutorial covers the whole loop, including policy for local builds.

For distribution, pack and publish prebuilt executables to an OCI registry. Declared packages install automatically when a command needs one of their exports, such as an authentication provider. First use outside CI creates a missing lock entry; CI refuses to, so commit the consumer's package declaration and lockfile. Later uses restore that exact digest without selecting upgrades. Verified cached packages require no registry access.

Get Involved​

Try the OIDC walkthrough with a dedicated test application and broker. Native auth providers, auth identities, and command exports are the first supported capabilities; additional Atmos primitives and scripting runtimes remain future work.

The Problem​

Configure custom delimiters once:

templates:
  settings:
    delimiters: ["[[", "]]"]

Stack manifests then render [[ .vars.stage ]]. A step in a workflow, a custom command, or a lifecycle hook ignored the setting and still rendered {{ .steps.first.value }}. One project could therefore have two template syntaxes depending on where a value was written.

The Fix​

Step templates now use the configured delimiters. With the configuration above:

• [[ .steps.first.value ]] renders in a step field.
• {{ .steps.first.value }} stays literal text, so shell commands and scripts can contain it unchanged.

This covers the template fields of every step in workflows, custom commands, and lifecycle hooks, including the children of parallel and matrix steps and the multi-pass rendering that protects flag values from being rendered a second time.

How to Use It​

A custom command using the configured delimiters:

templates:
  settings:
    delimiters: ["[[", "]]"]

commands:
  - name: show-container
    steps:
      - name: first
        type: shell
        command: echo first
      - type: shell
        command: |
          echo "got [[ .steps.first.value ]]"
          docker inspect --format '{{.State.Status}}' my-container

The second step prints got first and passes {{.State.Status}} to Docker as written.

Compatibility​

This change is selected by your edition, as of 2026-10-19:

• Before: workflow, custom command, and hook step templates always used {{ }}, even when templates.settings.delimiters was set.
• After: step templates use templates.settings.delimiters. Without that setting, or with the default ["{{", "}}"], nothing changes.

The new behavior applies to unpinned projects and to projects pinned to 2026-10-19 or later. To keep the previous behavior, pin an edition before the transition:

edition: "2026-10-18"

Projects with custom delimiters that write {{ }} in step fields need one of two changes when they adopt the new behavior: rewrite those fields with the configured delimiters, or keep the earlier pin. Run atmos describe edition to see every behavior an edition pin selects.

Get Involved​

Try custom delimiters in one workflow and share what you find in GitHub Discussions.

The Problem​

Real infrastructure demos include time spent waiting for providers and services. Those waits belong in the execution, but they can dominate a short recording. Removing frames loses the progress that explains what happened.

The Fix​

A playback group preserves every captured event and scales its timestamps to fit an exact duration. Typing and reading pauses outside the group retain their original timing. The command still runs normally, with real timeouts and live output during recording.

How to Use It​

Inside a cast session, wrap Enter and the completion wait in a group:

- type: write
  text: atmos terraform deploy --stack dev --all
- type: playback
  duration: 4s
  steps:
    - type: key
      key: enter
    - type: wait
      regex: '(?s)Apply .*completed.*> '
      timeout: 90s
- type: pause
  duration: 3s

The four seconds begin before Enter and end when the completion wait matches. The following three-second pause gives viewers time to read the result at the returned prompt. Elapsed times printed by the command still show the actual execution time; they are part of the preserved output.

The duration must be positive. Shorter segments stretch to fit, and playback groups cannot nest. Groups also work around ordinary steps in a steps-mode cast.

Get Involved​

See the cast documentation for recording options, and share feedback in GitHub Discussions.

The Problem​

A failed job hides its cause. CI providers show a step's exit status at a glance, but the explanation stays in the log. That costs a reviewer a click and a search on every failure. For policy denials it is worse: the policy author's guidance, such as "EIPs cannot be destroyed; use prevent_destroy instead," is only useful if someone reads it.

The Fix​

When a command fails in CI, Atmos reports the failure through the CI provider's annotation support:

• Policy denials produce one annotation per rule that denied the run. The title names the rule, and the message is the rule's reason as plain text, or "Denied by <rule>." when the rule has none.
• Any other failure produces one annotation from the error's title, message, and explanation.
• Location: when Atmos knows the file and line where the cause is defined, the annotation is anchored there.
• Scripts: a nested Atmos command that fails inside a script reports its own failure once. The script that called it does not repeat it.

On GitHub Actions, these are ::error workflow commands, which appear in the run's annotations:

::error title=Policy protect-prod/guard denied execution::Production components cannot be changed from this workstation.

How to Use It​

Failure annotations follow the same switches as other CI annotations:

ci:
  enabled: true
  annotations:
    enabled: true   # default when ci.enabled is true

A command policy is evaluated before atmos.yaml loads. A denial at that point is annotated whenever a CI provider is detected, because an annotation is the only CI signal it can produce.

Try it out​

atmos init examples/policies
cd policies

atmos policy check
atmos policy list
atmos policy test tests/cases.json

Get Involved​

Enable CI annotations in one workflow, trigger a policy denial, and share feedback in GitHub Discussions.

Previously, templates received Terraform documentation as an already-formatted terraform_docs string. The new function provides the parsed module directly, including methods such as .GetValue and .Type.Raw and source positions.

Enable Terraform documentation and select your template:

docs:
  generate:
    readme:
      base-dir: .
      template: "./README.md.gomplate"
      output: "./README.md"
      terraform:
        enabled: true
        source: .

Then choose how to present the data:

{{ with terraform }}
## Optional Variables
{{ range .OptionalInputs }}
### `{{ .Name }}`

{{ .Description.Raw }}

Type: `{{ .Type.Raw }}`

Default: `{{ .GetValue }}`
{{ end }}
{{ end }}

Run atmos docs generate readme to render it. The with guard also handles disabled Terraform generation or a missing configured source directory. Existing templates can continue using terraform_docs. Its visibility, hide_empty, and indent_level settings now work for unpinned projects and editions on or after 2026-10-17; earlier edition pins preserve the previous formatter behavior. The native objects remain available regardless of these settings.

Atmos 1.232.0 and earlier cannot parse the new function, even inside a guard. Upgrade the repository's Atmos version before adopting a native template.

See Custom Terraform formatting for the available objects and a complete example adapted from Cloud Posse's component README design.

The Problem​

Atmos can store a Terraform planfile after plan and verify it before deploy, so the plan you reviewed is the plan you apply. The store that holds it is configured per project under components.terraform.planfiles.stores.

The catch was authentication. When a component authenticated with a non-AWS identity, the S3 planfile store inherited that same identity and then tried to resolve AWS credentials from it. A azure/subscription identity authenticates just fine, but it produces no AWS auth context, so the upload failed:

failed to upload planfile: failed to load AWS configuration:
failed to resolve AWS auth context for identity "azure-plan":
auth context not available for identity

The shape of the problem is general: there was no way to say "authenticate the component one way, but authenticate the planfile store another way." The two were locked together. (The same mismatch will apply in reverse once non-AWS planfile backends land; today the S3 store is the one that trips on it.)

The Fix​

Planfile stores now take an optional identity field, naming the Atmos Auth identity the store authenticates with, independent of the component's identity. It works like the identity field on general Atmos stores you may already use.

components:
  terraform:
    planfiles:
      default: s3
      stores:
        s3:
          type: aws/s3
          identity: aws-backend    # store authenticates with this identity
          options:
            bucket: my-terraform-planfiles
            region: us-east-1

The component keeps using its own identity for the Terraform run, while the store uses aws-backend only for upload and download. The store identity isn't limited to ambient credentials: for the S3 store, any AWS-capable identity - aws/assume-role, aws/permission-set, and the like - is resolved through the same Atmos Auth chain, not merely passed through from the runner environment.

When identity is omitted, the store inherits the component's identity exactly as before, so existing single-cloud projects need no changes.

How to Use It​

Define the two identities in auth.identities - one the component uses, one the store uses - and point the store at the second:

auth:
  identities:
    azure-plan:                    # the component's default identity (non-AWS)
      kind: azure/subscription
      default: true
      # ...
    aws-backend:                   # AWS identity, used only by the planfile store
      kind: aws/assume-role
      # ...

components:
  terraform:
    planfiles:
      default: s3
      stores:
        s3:
          type: aws/s3
          identity: aws-backend
          options:
            bucket: my-terraform-planfiles
            region: us-east-1

See the Store Identity documentation for the full configuration reference, and the per-store identity example for a complete, working project.

Try it out​

atmos init examples/planfile-store-identity
cd planfile-store-identity

atmos validate stacks

Get Involved​

This shipped from a real multi-cloud setup where the plan-then-deploy workflow crossed a credential boundary. If your pipeline spans clouds in ways this does not yet cover, open an issue or a discussion on GitHub - the planfile store and the broader auth system keep growing from exactly these cases.

The Problem​

A label such as preview should be enough to enable preview behavior and select the affected components that participate. Keeping that decision in workflow scripts duplicates configuration and separates it from the components it controls.

The Fix​

The !ci.labels function reads live labels on the current CI review. GitHub Actions is the first supported provider, including GitHub Enterprise. Atmos fetches every page on first use and caches the resulting snapshot for the entire invocation, so components share one consistent result without repeated API requests. The next invocation fetches fresh labels.

Merge-queue runs use the labels of the individual PR being tested. Labels from earlier queued PRs do not affect that run, even when their changes are included in the checkout.

Outside a review context, matching returns false and list mode returns [], without credentials or API calls. Authentication and API failures in a review context remain errors.

How to Use It​

Set a boolean component label alongside the preview setting:

components:
  terraform:
    preview:
      metadata:
        labels:
          preview: !ci.labels [preview]
      settings:
        pro:
          enabled: !ci.labels [preview]

Then filter the affected components:

atmos describe affected --labels preview:true

Use !ci.labels [preview, deploy] to require both labels, or bare !ci.labels to retrieve a sorted list. Matching is exact and case-sensitive; quote names containing spaces, such as !ci.labels ["needs review"].

In GitHub Actions, pass GITHUB_TOKEN: ${{ github.token }} to the Atmos step with pull-requests: read permission. See the credentials and snapshot documentation for token precedence, Enterprise configuration, and examples.

Get Involved​

Share feedback and requests for additional CI providers in GitHub Discussions.

Since then, we, our customers, and the community have put many of these features to work in production. That use has brought valuable feedback. Interfaces have stabilized, functionality has been validated, and feedback has increasingly shifted from critical problems toward refinements and nice-to-haves.

We're graduating Atmos CI, Atmos Auth, Atmos Toolchain, Atmos Emulator, and source vendoring to stable. These capabilities have demonstrated stable interfaces and real-world use; this release formalizes their supported status. Other features will keep the experimental designation while we continue assessing them.

The Problem​

These capabilities have become part of everyday infrastructure delivery while still carrying experimental warnings. Some roadmap entries already omitted the experimental label, while commands and documentation retained it. Teams needed a consistent answer about which interfaces they could rely on.

We applied the existing graduation criteria and reviewed the preceding 90 days of available history. That is an evidence window, not a claim that every feature went 90 days without a bug or a requirement to wait another quarter before recognizing established use.

The Fix​

The following capabilities now have stable command and configuration interfaces:

Here's what that use looks like:

• CI and Toolchain run in production at dozens of our own customers, with broader adoption across the community.
• We've used Auth exclusively for several months. CI, Auth, and Toolchain are frequently used together in production.
• Nearly all of our demos use the Emulator functionality. Repeatedly exercising infrastructure locally has helped identify and fix problems in Atmos itself.
• We use source vendoring ourselves, and we've seen substantial community adoption. It went through a rough patch; that feedback led to fixes for retrieval failures and workdir interactions.

Atmos Auth, Toolchain, and CI commands have been executed more than a million times in the past 90 days. Anonymous telemetry recorded 1,030,935 executions from July 17 through October 14, 2026, without an extrapolation multiplier. This counts explicit command executions; embedded use of these features inside other commands is not separately counted.

Auth's adoption extends beyond CI automation: nearly 120,000 authentication commands were run outside CI pipelines during the same period.

We've seen relatively few reports affecting core functionality across these features. We combined that experience with regression checks; neither means bugs cannot occur. Recent fixes remain part of the record. Newer providers and integrations, including Azure, have less production history than the established features. Emulator's stable status concerns Atmos's lifecycle interface; it does not promise that a third-party emulator implements every cloud API.

Source vendoring includes automatic workdir use for remote component sources. The terraform workdir commands also graduate, covering listing, inspecting, and cleaning component working directories.

Atmos CI also works with Atmos Pro, which is already used in production.

How to Use It​

Upgrade Atmos. No configuration changes are required; your existing commands and configuration continue to work. The graduated features no longer display experimental warnings.

atmos config set settings.experimental silence

The remaining experimental features keep their labels and restrictions. Affected-component detection, Devcontainers, backend provisioning, and other candidates will graduate when their own evidence supports it. We expect another round of promotions soon, with Kubernetes, Helm, and container components next in the review.

Get Involved​

Continue reporting reproducible problems through GitHub Issues. Include the Atmos version, a minimal configuration, and the expected behavior, with credentials and identifying infrastructure details removed. Real-world use and regression reports help us assess the next candidates.

The Problem​

Provider-maintained attributes can vary independently of configuration changes. As reported in #2088, comparing RDS plans can report differences in latest_restorable_time that a project wants to ignore.

The Fix​

The new components.terraform.plan_diff.ignore_changes setting applies exclusions consistently to the displayed diff and the comparison result. Both atmos terraform plan-diff and deployment plan verification honor the same configuration.

Other attribute changes, resource additions and removals, action changes, and replacement metadata remain detectable. Variables and outputs are compared independently, including outputs that export an excluded attribute.

How to Use It​

Add an exact resource type and top-level attribute to atmos.yaml:

components:
  terraform:
    plan_diff:
      ignore_changes:
        - aws_db_instance.latest_restorable_time

This entry applies to all instances of aws_db_instance, including those inside modules. Wildcards, nested paths, and unqualified attribute names are rejected before Terraform runs.

These exclusions control Atmos comparisons. They do not change Terraform's lifecycle.ignore_changes, resource updates, plans, or state.

Existing projects and editions​

No attributes are automatically excluded from comparisons. Content hashes and encoded response bodies can represent real changes, so exclude them only when your project expects those changes.

Atmos previously hid seven attributes from displayed diffs while still reporting a comparison failure for their differences. The 2026-10-13 edition displays them: response_body_base64, content_base64sha256, content_base64sha512, content_md5, content_sha1, content_sha256, and content_sha512. Unpinned projects get the new display too. A pin before that date preserves the old display-only suppression and still detects the differences. Explicit exclusions work identically under every edition.

Get Involved​

See the plan-diff documentation for command usage, and report unexpected comparison behavior with a sanitized example.

The Problem​

Project health checks span configuration schemas, stack validation, formatting, CI workflows, and upstream sources. Deprecation guidance identifies replacement fields, but a replacement is safe only when its behavior matches the original configuration.

The Fix​

Doctor combines built-in checks in a streaming report. Supported repairs cover custom-command semantic arguments and flags, recognized legacy hook events, explicit Terraform reconfigure values, simple legacy settings.depends_on lists, and component sources that point at archived repositories. Each repair compares runtime field behavior and unrelated YAML values before writing, and comments on a migrated field move with it. A repair is blocked only by inputs that can change what it means, such as an import, an active profile, or a template in the edited value, and the finding names the file and line responsible. Templates elsewhere in the file do not get in the way. Repaired files can have blank lines or folded scalars reformatted, so review the diff before committing.

A simple dependency list, where each entry names a component and optionally its stack, moves to dependencies.components and adopts modern required semantics on purpose: a missing or disabled target that only produced a warning before is now reported as an error, so you see it before it breaks a deployment. Context selectors, file and folder entries, and stack naming migrations remain manual.

GitHub source metadata identifies archived repositories and distinguishes inaccessible sources from confirmed removal. The health check itself never rewrites source URLs. The one exception is the component-monorepo repair, which moves a source to its successor repository at the same version only after verifying the files are identical. Access errors, private-repository 404 responses, and unsupported hosts remain inconclusive.

How to Use It​

Start with a diagnosis, then inspect a verified dry run:

atmos doctor
atmos doctor --fix --dry-run
atmos doctor --fix

The verification and recovery report explains repairs and skipped migrations. Before writing, doctor warns about affected Git changes or unavailable Git and saves exact originals in a private backup directory. Each replacement is atomic; partial failures report exactly which files changed.

For CI, use JSON or SARIF output. Warnings are advisory by default; select --fail-on=warning to make them blocking. Use --offline to skip repository requests; the skipped checks are reported as notices that never trip --fail-on=warning. Doctor exits 2 for invocation errors and when it cannot find a project configuration, and with JSON output those errors arrive in an operational_error field.

Get Involved​

Read the command reference and share unsupported migration cases in Atmos discussions.

The Problem​

Guardrails scattered across workflow scripts are difficult to apply consistently. A destructive replacement can slip past a deletion-only check, and an optional hook can be skipped even when your deployment process requires it.

The Fix​

The opt-in policy integration evaluates native saved-plan JSON after Terraform planning and again before applying a private copy of the selected artifact. Lifecycle policies can deny operations or select existing hooks for Terraform, Helmfile, native Helm, and native Kubernetes. Required hooks cannot be skipped with --skip-hooks; requiring execution and requiring success are separate choices.

GitHub Actions policies can inspect allowlisted runner metadata and the supplied native event without API credentials or additional token permissions. Missing required context blocks evaluation. The event records the trigger, not current review state. Policies evaluate the input and required hooks for the current invocation.

How to Use It​

Place this document in a protected policy directory:

apiVersion: atmos/v1
kind: Policy
metadata:
  name: safety
spec:
  policies:
    protect-databases:
      on: terraform.plan
      action: deny
      reason: Database deletion and replacement require a different deployment process
      rule: >-
        has(input.resource_changes) && input.resource_changes.exists(r,
          r.mode == 'managed' && r.type == 'aws_db_instance' &&
          'delete' in r.change.actions)

Then run an explicit plan and saved-plan apply:

export ATMOS_POLICY_DIR=/trusted/policy.d
atmos terraform plan database -s prod
atmos terraform apply database -s prod --from-plan

With plan policies configured, implicit apply/deploy and direct destroy are rejected. These checks do not require --affected. Dry-run does not evaluate a saved plan and is not policy approval.

Protect the governing directory, workflow, environment, and executable dependencies: this opt-in feature is not a sandbox against someone who controls the runner. A failed post-apply hook can fail the command, but cannot undo the completed apply.

See Policy Configuration for the manifest and trust boundary, Terraform Plans for saved-plan checks, and Hooks for required lifecycle actions.

Try it out​

atmos init examples/policies
cd policies

atmos policy check
atmos policy list
atmos policy test tests/cases.json

Get Involved​

Try the tested policy demonstrations and share feedback in GitHub Discussions.

That is what asking a question from the terminal has felt like when the AI runs through Claude Code. Atmos now keeps the conversation open: it shows you what the AI wants to do, lets you approve it, lets the AI ask you to choose, and lets you follow up without starting over.

The Problem​

Claude Code runs without a terminal of its own when Atmos starts it for a one-off question. It cannot ask you anything, so it refuses any tool that needs permission and then describes the refusal in its answer. You see a request for approval that you have no way to give.

Two more rough edges made it worse:

• Nothing showed that work was in progress, so a slow answer looked the same as a hung command.
• Answers often ended with an offer ("I can break that down by tenant if you'd like") that you could only accept by retyping the whole question.

The Fix​

atmos ai ask is now interactive when it runs through the claude-code provider.

Approval in the same run. When the AI needs to run a command, Atmos pauses and shows the request in a block that wraps to your terminal width, with the command in its own panel. You choose Allow once (the default), Always allow, Deny once, or Always deny. The AI waits for your answer and continues in the same run. A one-line receipt stays behind so you can see what you approved.

Choices instead of guesses. When the AI needs you to pick between options or confirm something, it asks with a selection list. You choose with the arrow keys, or choose Other to type your own answer. Your choice goes straight back to the AI.

Progress you can see. A spinner shows that work is happening and names the command in progress, for example Running atmos list stacks. It steps aside while a prompt is on screen, and Ctrl-C cancels the request.

Follow-up questions. After an answer, a prompt offers to continue. Type a reply and the AI answers with the earlier questions and answers as context, so a short "yes, by tenant" is enough. Press Enter on an empty line to finish.

Answers are also written in Markdown with the command, file, and stack names set off as code, so they read well in the terminal.

How to Use It​

Ask as usual. With the Claude Code CLI installed, Atmos prompts when approval is needed:

atmos ai ask "how many stacks do we have?"

Approvals you choose to keep are saved in .atmos/ai.settings.local.json. For Bash commands, Always allow applies to that exact command, so a different command asks again.

One setting now controls how tool requests are approved. The new ai.tools.mode option replaces the pair of booleans yolo_mode and require_confirmation:

ai:
  tools:
    enabled: true
    mode: require_confirmation   # default: prompt for tools that need approval
    # mode: allow                # never prompt; ai.tools.blocked still applies
    # mode: yolo                 # never prompt and skip the blocked and restricted checks

The old settings still work as aliases, and mode wins when both are set. The AI tools configuration page describes each mode.

Follow-up questions and selection lists appear only when both input and output are a terminal and the command is not running in CI. When you pipe the output or run in a pipeline, ask prints the answer and exits, and a command that would need approval fails with an error that names it and suggests mode: allow.

If you configure mcp.servers, Atmos used to start Claude Code with every tool call pre-approved. For ask and exec, those calls now go through the same approval as everything else. Set ai.tools.mode: allow for unattended runs, or yolo in an isolated runner.

An empty answer, for example when Claude Code runs out of turns, is now reported as an error with a hint to raise ai.providers.claude-code.max_turns, instead of printing a blank line.

Get Involved​

This feature is experimental. If an approval, a question, or a follow-up does not behave the way you expect, open an issue with the command you ran and what you saw.

The Problem​

Installing a repository manually records an action, but does not give a team a shared declaration of the skills, plugins, clients, and versions their project needs. A marketplace may also reference plugins in other repositories, each advancing independently.

The Fix​

Declare sources under ai.skills and commit the resulting skills lock. Configuration commands edit those declarations independently of installation. Project installations have their own ownership records, and ordinary synchronization retains obsolete copies until you explicitly prune them.

Managed refs can use the version function to follow an Atmos version track.

How to Use It​

atmos ai skill add cloudposse/atmos --name cloudposse
atmos ai skill set cloudposse plugins '[atmos]'
atmos ai skill sync
atmos ai skill sync --frozen
atmos ai skill sync --check

Commit skills.lock.yaml and ignore .atmos/skills/. See the configuration reference for managed versions, local sources, explicit pruning, and recovery.

Migrating Claude Code Automation​

Existing MCP configurations previously caused Claude Code to approve every tool automatically. The atmos ai chat, atmos ai ask, and atmos ai exec commands now enforce Atmos tool permissions for requests Claude delegates to Atmos. Native and provider-preapproved requests follow Claude’s own permission policy. With the default confirmation policy, unattended runs fail when a tool needs approval.

Before upgrading CI jobs, set an explicit policy. For example, allow avoids prompts while still enforcing blocked tools on delegated requests:

ai:
  tools:
    mode: allow
    blocked: ["Edit", "Write"]

For narrower approvals, configure ai.providers.claude-code.allowed_tools with the specific Claude Code tools your job needs. The yolo mode bypasses all Atmos permission checks, including blocked tools. Edition pins do not restore the former implicit approval. See the automation migration guide.

Get Involved​

Report issues and share your workflows in the Atmos repository.

The Problem​

A git provision target renders the manifests for a Helm, Helmfile, or Kubernetes component and commits them to a deployment repository. Until now it could only push to the repository's configured branch. Teams that protect that branch had two options: open an exception for the deploy identity, or wrap Atmos in scripts that create a branch, push it, and call the forge API to open a pull request.

The Fix​

Set pull_request.enabled on the target. Atmos commits the rendered manifests to a head branch, pushes it (never the base), and opens a pull request into the repository's branch, or into the remote's default branch when none is configured. If that pull request already exists, Atmos updates it.

• Re-deliveries stack onto the open branch as new commits, and the same pull request updates in place. Atmos never force-pushes.
• Identical re-deliveries create no commit. A rerun still reconciles the pull request, which recovers a run where the push succeeded but the pull request call failed.
• GitHub and Azure DevOps are both supported, and Atmos detects which one from the repository URI. Title, body, labels, reviewers, assignees, and draft status are configurable, and the text fields support templates.

This applies everywhere a git target is used: atmos helm deploy, atmos helmfile template --target, and atmos kubernetes apply / deploy.

How to Use It​

git:
  repositories:
    deployments:
      uri: https://github.com/acme/deployments.git
      branch: main               # the pull request base

components:
  helm:
    monitoring:
      provision:
        targets:
          deployment-repo:
            kind: git
            repository: deployments
            path: "clusters/{{ .vars.stage }}/monitoring"
            pull_request:
              enabled: true
              title: "Deploy monitoring to {{ .vars.stage }}"
              labels: [gitops]
              reviewers: [platform-team]

atmos helm deploy monitoring -s plat-ue2-dev --target deployment-repo

Git credentials work as they already do for git targets, including GIT_CONFIG_* headers set in CI. The pull request API token comes from GITHUB_TOKEN (or ATMOS_CI_GITHUB_TOKEN / GH_TOKEN) for GitHub, and from AZURE_DEVOPS_EXT_PAT for Azure DevOps. See Publishing through a pull request for every option.

Try it out​

atmos init examples/gitops
cd gitops

atmos git clone deploy
atmos git status deploy

Get Involved​

Try it on your deployment repository and tell us how it fits your review flow in GitHub Discussions or the SweetOps Slack.

The Problem​

As reported in issue #3342, --no-color could still produce colored debug logs in GitHub Actions. Forced color could also override the flag. In our reproduction, 19 of 20 log lines contained ANSI escapes despite the explicit opt-out.

The Fix​

The --no-color flag and a nonempty NO_COLOR environment variable now take precedence throughout startup, logging, and UI output, including when color is forced. GitHub Actions still gets color by default because it supports it.

The new boolean logs.color setting controls Atmos log color independently:

• true (the default) uses color when available, following existing terminal and CI detection.
• false removes ANSI escapes from logs, including preformatted log messages.

Use the existing --force-color or ATMOS_FORCE_COLOR=true controls to force color when log color is enabled. Global color opt-outs always win.

How to Use It​

Disable log color in your project configuration:

logs:
  color: false

Or save a plain debug log for one invocation while retaining terminal UI colors:

atmos --logs-level=debug --logs-file=/tmp/atmos.log --logs-color=false version

You can also set ATMOS_LOGS_COLOR=false. The command-line flag takes precedence over the environment variable, which takes precedence over configuration. These controls affect Atmos logs; child-process output keeps its own color settings.

To disable color throughout Atmos, including its UI, use:

atmos --logs-level=debug --logs-file=/tmp/atmos.log --no-color version

Get Involved​

See the logging documentation for configuration details. If you encounter another color opt-out regression, open an issue with your command and terminal or CI environment.

The Problem​

Atmos already reads .tool-versions for atmos toolchain commands and workflows, but component runs only looked at explicit dependencies.tools in stack configuration. A project that pinned its tools in one file still got whatever executable the machine offered when it ran atmos terraform plan, atmos helmfile diff, or a !terraform.output lookup. Custom commands and hooks ignored the file too.

Fixing that naively would create new problems. Many .tool-versions files are shared with asdf or mise and list tools Atmos doesn't manage (nodejs, python) or versions like system. And nobody wants atmos describe stacks to download every tool in the file just to evaluate a template.

The Fix​

The project's .tool-versions is now a baseline for every command and component type, with installs limited to what a run actually executes:

• Components install their own executable when the file pins it — terraform, tofu when the component sets command: tofu, helmfile (plus helm), packer, or ansible. Other tools in the file are added to PATH only if they're already installed. Nothing else is downloaded during a component run, including read-only commands like describe, plan --dry-run, and terraform version.
• Every Atmos command inherits already-installed versions selected by the file on PATH. Cached tools absent from the file, and other cached versions, are not added.
• Custom commands and hooks install only their own dependencies.tools.
• Workflows keep their existing behavior: they install every listed tool that is missing before the first step.

How much Atmos installs on its own is a setting, so you can make it more or less eager (see Control What Atmos Installs).

Explicit dependencies.tools always win, even when one side uses a short name or alias and the other uses owner/repo. Entries Atmos can't use — system, ref: and path: versions, unknown tools, lines without a version, or ~> 1.15.0 written with a space — are skipped instead of failing the run. Two entries for the same tool with different versions (tofu 1.12.6 and opentofu/opentofu 1.11.0) now stop with an error naming both, instead of picking one at random.

How to Use It​

Pin the tool once:

hashicorp/terraform 1.15.8

Every component without an override runs Terraform 1.15.8, installing it on first use. Override a single component when it needs something else:

components:
  terraform:
    legacy-vpc:
      dependencies:
        tools:
          terraform: "1.15.6"

Running legacy-vpc uses 1.15.6 and leaves .tool-versions untouched. If your configuration points at a different manifest, toolchain.file_path is now honored everywhere.

If a component previously relied on a binary from PATH while .tool-versions pinned a different version, it now runs the pinned version. Remove or update the pin, or set dependencies.tools on the component, to keep the old binary.

Control What Atmos Installs​

The new toolchain.install setting controls downloads separately from version selection. Every command inherits installed project selections under every policy; explicit dependencies.tools override them. The setting decides which missing tools Atmos installs on its own:

toolchain:
  install: auto   # never | declared | auto | always

• never installs nothing. Tools are used only when they are already installed, and a missing dependencies.tools entry fails with a hint to run atmos toolchain install. Use it on air-gapped runners or when an image bakes in every tool.
• declared installs only explicit dependencies.tools (and, for workflows, every .tool-versions tool). Other runs use already-installed project selections without installing missing defaults.
• auto is the default and the behavior described above.
• always installs every tool in .tool-versions for every run, including custom commands and hooks.

Projects pinned to an edition dated before 2026-10-09 keep declared automatically, preserving their automatic download policy. Installed project selections still supply the baseline under every policy. Set ATMOS_TOOLCHAIN_INSTALL to override the setting for a single run.

Get Involved​

Questions or edge cases with your .tool-versions? Open an issue or join the conversation in the Cloud Posse community.

The Problem​

Someone new to Atmos should be able to kick the tires almost immediately. A working example provides the configuration, stacks, and components to start exploring with just a few commands.

The Fix​

Start with any of the official Atmos examples. Atmos copies the example verbatim, including examples that contain a scaffold manifest.

The same command also works with directories in other Git repositories, supported remote sources, and local directories. These sources use scaffold generation when a root manifest exists and copy their contents otherwise.

Git sources use a single shallow fetch to avoid downloading repository history. Configure init.depth for any repository: use 1 for the latest revision or 0 for full history. A source URL's explicit depth parameter takes precedence. The CLI prints the actual destination and displays the example's README when present.

Copies preserve literal template content, dotfiles, executable permissions, and empty directories while excluding Git metadata. Existing template names and interactive selection continue to work.

How to Use It​

The quick start below initializes a complete project and lists its stacks. The destination defaults to the source directory's name. Supply a second argument to choose another destination:

atmos init examples/quick-start-simple ./my-project

Configure initialization defaults in atmos.yaml to use your team's repository and revision:

init:
  repository: github.com/acme/starters
  ref: main
  depth: 1
  git: true

The repository defaults to github.com/cloudposse/atmos. Git initialization and an initial commit are enabled by default; set git: false or pass --no-git to skip them. Explicit source URLs bypass the default repository, and a revision embedded in the source takes precedence over --ref and configuration.

Use --copy to copy another source verbatim even when it contains a scaffold manifest. Copy mode skips template rendering and scaffold hooks, requires an empty destination unless --force is supplied, and does not support scaffold updates or template variables. Read the init reference for source formats, precedence, and overwrite behavior.

Try it out​

atmos init examples/quick-start-simple
cd quick-start-simple

atmos list stacks

Get Involved​

Explore the examples and share your experience in GitHub Discussions.