The Problem​

When using atmos describe affected to identify components impacted by code changes, the command was only detecting stack configuration changes but missing actual component file changes. For example, modifying a main.tf file inside a Terraform component folder would not mark that component as affected.

This issue occurred because git diff returns file paths relative to the git repository root, while the path resolution was using the current working directory. This caused path mismatches in the following scenarios:

• Using -C flag: Running atmos -C path/to/project describe affected from a parent directory
• Subdirectory projects: When atmos.yaml is located in a subdirectory of the git repository
• Monorepo setups: When multiple Atmos projects share a single git repository

The Fix​

We updated the changed files indexing logic to properly resolve relative paths against the git repository root instead of the current working directory. The fix ensures that:

• Relative paths from git diff are correctly resolved against the git repo root
• Component folder changes are detected regardless of where Atmos is executed from
• Individual file changes within component directories are properly tracked

Example​

Now when you modify component files, atmos describe affected correctly identifies them:

# Modify a component file
echo "# comment" >> components/terraform/vpc/main.tf

# Run describe affected
atmos describe affected --ref refs/heads/main

# Output now includes the vpc component
[
  {
    "component": "vpc",
    "stack": "plat-ue2-dev",
    "affected": "component"
  }
]

Usage​

Upgrade to the latest version of Atmos and run:

atmos describe affected --ref refs/heads/main

The command now correctly detects:

• Changes to component folders (Terraform, Helmfile, Packer)
• Changes to individual files within components
• Stack configuration changes (as before)
• Vendored components configured with source (even without an explicit component field)

This fix ensures your CI/CD pipelines accurately identify which components need to be deployed based on actual code changes.

The Problem​

When using Atmos vendoring with the source attribute to pull components from remote repositories, the atmos describe affected command was not detecting changes to those component files. This occurred because the affected detection logic required an explicit component field to determine which folder to monitor for changes.

Components configured like this were not being tracked:

components:
  terraform:
    vpc-remote:
      source:
        uri: "github.com/cloudposse/terraform-aws-vpc//."
        version: "4.0.0"
      vars:
        enabled: true

The Fix​

The affected detection now defaults to using the component name (the YAML key, e.g., vpc-remote) as the component folder path when no explicit component field is specified. This ensures that:

• Components using source for vendoring are properly tracked
• Components without explicit component field inheritance are detected
• All component types (Terraform, Helmfile, Packer) benefit from this fix

What About Workdir?​

If you use provision.workdir with your vendored components, the detection still works correctly. The describe affected command tracks changes in the source files (components/terraform/<component>/), not the runtime workdir (.workdir/). Since .workdir/ is in .gitignore and created at runtime, it doesn't affect change detection.

Example​

Now when you modify vendored component files, atmos describe affected correctly identifies them:

# Stack configuration with source vendoring
components:
  terraform:
    vpc-production:
      source:
        uri: "github.com/cloudposse/terraform-aws-vpc//."
        version: "4.0.0"
        included_paths:
          - "**/*.tf"
      vars:
        environment: "production"

After running atmos vendor pull and making changes:

# Modify a vendored component file
echo "# update" >> components/terraform/vpc-production/main.tf

# Run describe affected
atmos describe affected --ref refs/heads/main

# Output now includes the vpc-production component
[
  {
    "component": "vpc-production",
    "stack": "prod-us-east-1",
    "affected": "component"
  }
]

Related Documentation​

• Vendoring Overview - Learn about Atmos vendoring capabilities
• Source Configuration - Configure source URIs and protocols
• Just-in-Time Vendoring - Inline source declarations
• Vendor Pull Command - Download vendored components

The Feature​

Locals can now use all Atmos YAML functions to fetch dynamic values:

• !env - Environment variables
• !exec - Command execution
• !store - Store lookups
• !terraform.state - Terraform state queries
• !terraform.output - Terraform outputs from other components

Example with Environment Variables​

locals:
  api_endpoint: !env API_ENDPOINT
  api_url: "https://{{ .locals.api_endpoint }}/api/v1"

components:
  terraform:
    myapp:
      vars:
        api_url: "{{ .locals.api_url }}"

Example with Terraform State​

locals:
  # Fetch from another component's terraform state
  vpc_id: !terraform.state vpc .vpc_id
  subnet_ids: !terraform.state vpc .private_subnet_ids

components:
  terraform:
    eks:
      vars:
        vpc_id: "{{ .locals.vpc_id }}"
        subnet_ids: "{{ .locals.subnet_ids }}"

Example with Store​

locals:
  db_password: !store secrets/database .password
  connection_string: "postgresql://app:{{ .locals.db_password }}@db.example.com/mydb"

components:
  terraform:
    backend:
      vars:
        database_url: "{{ .locals.connection_string }}"

How It Works​

1. YAML functions in locals are processed during stack configuration loading
2. The resolved values are available to other locals and component vars
3. Locals can combine YAML function results with Go templates

Use Cases​

• Environment-specific configuration: Use !env to inject environment-specific values
• Cross-component references: Use !terraform.state to reference outputs from other components
• Secret management: Use !store to fetch secrets from your configured store
• Dynamic values: Use !exec to run commands and capture output

Upgrade​

Upgrade Atmos to get this feature. Existing locals configurations continue to work unchanged.

References​

• Locals Documentation
• YAML Functions Documentation

The Enhancement​

Previously, locals could only reference other locals via {{ .locals.* }}. Now they can also access:

• {{ .settings.* }} - Settings defined in the same file
• {{ .vars.* }} - Vars defined in the same file
• {{ .env.* }} - Environment variables

Example​

settings:
  version: v1

vars:
  stage: dev

locals:
  namespace: acme
  label: "{{ .locals.namespace }}-{{ .vars.stage }}-{{ .settings.version }}"

components:
  terraform:
    myapp:
      vars:
        name: "{{ .locals.label }}"

File-Scoped Context​

The context available to locals comes from the same file only. Locals cannot access settings or vars from imported files.

If you need values from imported files, use vars or settings (which inherit across imports).

Upgrade​

Upgrade Atmos to get this enhancement. Existing locals configurations will continue to work.

References​

• Locals Documentation
• DRY Configuration with Locals

What Changed​

Two new commands are available with flexible filtering:

# List all terraform sources across all stacks
atmos terraform source list

# List terraform sources in a specific stack
atmos terraform source list --stack dev

# List sources for a specific component across all stacks
atmos terraform source list vpc

# List sources for a specific component in a specific stack
atmos terraform source list vpc --stack dev

# Unified view: list sources across all component types
atmos list sources
atmos list sources --stack dev
atmos list sources vpc

Dynamic Output Columns​

The output adapts to your query:

Listing all stacks - Shows Stack column:

STACK        COMPONENT    URI                                                           VERSION
plat-dev     vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0
plat-prod    vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0

Filtering by --stack - Omits Stack column since it's redundant:

COMPONENT    URI                                                           VERSION
eks          github.com/cloudposse/terraform-aws-components//modules/eks   1.450.0
rds          github.com/cloudposse/terraform-aws-components//modules/rds   1.449.0
vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0

With derived components - Shows Folder column when component names differ from their base component:

COMPONENT        FOLDER    URI                                                           VERSION
vpc/production   vpc       github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0
vpc/staging      vpc       github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0

The Folder column only appears when there's a difference to show, keeping output clean for simple cases.

Multi-Type Listing​

The atmos list sources command includes a Type column since it lists sources across all component types (terraform, helmfile, packer) in a unified view:

STACK        TYPE        COMPONENT    URI                                                           VERSION
plat-dev     helmfile    nginx        github.com/cloudposse/helmfile-components//charts/nginx       1.0.0
plat-dev     terraform   vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0
plat-prod    terraform   vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0

Why This Matters​

With the source provisioner, components can declare their source inline in stack configuration for just-in-time vendoring. The source list command helps you:

• Audit which components have source configured across your infrastructure
• Compare versions across stacks (same component, different versions)
• Debug source configuration issues
• Discover vendorable components in unfamiliar stacks

Output Formats​

Multiple output formats are supported for integration with other tools:

# Table (default, human-readable)
atmos list sources --format table

# JSON (for scripting)
atmos list sources --format json

# YAML (for configuration)
atmos list sources --format yaml

# CSV (for spreadsheets)
atmos list sources --format csv

# TSV (for tab-separated pipelines)
atmos list sources --format tsv

Documentation​

• Source Provisioner - JIT vendoring overview
• atmos list sources - Unified view across all component types
• atmos terraform source list - List Terraform sources
• atmos helmfile source list - List Helmfile sources
• atmos packer source list - List Packer sources

What Changed​

The atmos toolchain env command now supports a github format that outputs paths compatible with GitHub Actions' $GITHUB_PATH environment file. When running in GitHub Actions, it automatically detects and writes to $GITHUB_PATH.

New Features​

• --format github: Outputs one path per line, compatible with $GITHUB_PATH
• --output flag: Append output to any file instead of stdout
• Auto-detection: When $GITHUB_PATH is set, the github format automatically writes to it
• Improved error messages: Helpful hints guide you when tools aren't installed

How to Use It​

In your GitHub Actions workflow:

- name: Install Atmos toolchain
  run: |
    atmos toolchain install
    atmos toolchain env --format github

The next step in your workflow will have access to all your toolchain binaries (OpenTofu, Terraform, Helmfile, etc.) in the PATH.

Why This Matters​

Previously, integrating Atmos toolchain with GitHub Actions required shell tricks:

# Before: Manual PATH manipulation
- run: echo "$(atmos toolchain path)" >> $GITHUB_PATH

Now it's a single, intuitive command that handles everything automatically.

Get Involved​

Try out the new GitHub Actions integration and let us know what you think! File issues or feature requests on GitHub.

What Changed​

When using atmos terraform plan -s stack-name without specifying a component, the interactive "Choose a component" menu now correctly filters the component list:

• Abstract components (metadata.type: abstract) are hidden - they're templates, not deployable
• Disabled components (metadata.enabled: false) are hidden - they can't be deployed
• Stack-scoped filtering - only components in the specified stack appear

Why This Matters​

Previously, users would see all components from all stacks, including abstract base components that serve as templates. This was confusing and could lead to errors when selecting a component that couldn't actually be deployed.

Shell Completion Too​

Tab completion for component arguments also uses the same filtering logic, so you'll only see valid, deployable components when completing atmos terraform plan -s stack <TAB>.

What's New​

The new --format=github option for atmos terraform output automatically writes outputs to $GITHUB_OUTPUT in the format GitHub Actions expects, including proper handling of multiline values using heredoc syntax.

# In a GitHub Actions workflow
atmos terraform output vpc -s dev --format=github

This writes outputs directly to $GITHUB_OUTPUT, making them available to subsequent workflow steps.

Why This Matters​

Previously, passing Terraform outputs between GitHub Actions steps required manual formatting or shell scripting to handle:

• Multiline values (JSON objects, lists, multi-line strings)
• Special characters that need escaping
• The correct $GITHUB_OUTPUT file format

The github format handles all of this automatically:

• Single-line values are written as key=value
• Multiline values use heredoc syntax: key<<DELIMITER\nvalue\nDELIMITER
• Complex types (maps, arrays) are JSON-encoded for easy parsing

Example Workflow​

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Get Terraform Outputs
        id: outputs
        run: atmos terraform output vpc -s dev --format=github

      - name: Use Outputs
        run: |
          echo "VPC ID: ${{ steps.outputs.outputs.vpc_id }}"
          echo "Subnets: ${{ steps.outputs.outputs.private_subnet_ids }}"

Usage Options​

Automatic $GITHUB_OUTPUT Detection​

When running in GitHub Actions, the format automatically writes to $GITHUB_OUTPUT:

atmos terraform output vpc -s dev --format=github

Custom Output File​

You can specify a different output file if needed:

atmos terraform output vpc -s dev --format=github --output-file=outputs.txt

Combined with Other Options​

The github format works with other output options:

# Uppercase keys for conventional ENV_VAR naming
atmos terraform output vpc -s dev --format=github --uppercase

# Flatten nested maps
atmos terraform output vpc -s dev --format=github --flatten

# Skip init for faster execution in CI
atmos terraform output vpc -s dev --format=github --skip-init

Output Format Details​

Simple Values​

vpc_id=vpc-12345
region=us-east-1
enabled=true

Multiline Values (Heredoc)​

For values containing newlines, the format uses GitHub's heredoc syntax:

vpc_config<<ATMOS_EOF_vpc_config
{
  "id": "vpc-12345",
  "cidr": "10.0.0.0/16"
}
ATMOS_EOF_vpc_config

Documentation​

For complete documentation on terraform output formatting options, see:

• Terraform Output Command

Get Involved​

Try out the new GitHub Actions output format and let us know what you think! File issues or feature requests on GitHub.

What Changed​

Previously, Atmos required users to specify a single HCL file via --template flag or settings.packer.template configuration. Running Packer commands without this setting would result in an error:

# Old behavior
atmos packer build my-ami -s prod
# Error: packer template is required

Now, Atmos defaults the template to . (component working directory) when not specified, allowing Packer to load all *.pkr.hcl files from the component directory automatically:

# New behavior - works out of the box
atmos packer build my-ami -s prod
# Packer loads all *.pkr.hcl files from the component directory

Why This Matters​

HashiCorp recommends organizing Packer configurations across multiple files for better maintainability:

• variables.pkr.hcl - Variable declarations
• main.pkr.hcl or template.pkr.hcl - Source and build blocks
• locals.pkr.hcl - Local values
• plugins.pkr.hcl - Required plugins

When users followed this practice, Atmos would only load the specified template file, causing "Unsupported attribute" errors when variables were defined in separate files. This change aligns Atmos with Packer's native behavior and HashiCorp best practices.

How to Use It​

Directory Mode (New Default)​

Simply organize your Packer component with multiple files and run commands without specifying a template:

components/packer/my-ami/
├── variables.pkr.hcl    # Variable declarations
├── main.pkr.hcl         # Source and build blocks
├── locals.pkr.hcl       # Local values (optional)
└── plugins.pkr.hcl      # Required plugins (optional)

# Stack configuration - no template needed
components:
  packer:
    my-ami:
      vars:
        region: us-east-1
        instance_type: t3.medium

# All commands work without --template
atmos packer init my-ami -s prod
atmos packer validate my-ami -s prod
atmos packer build my-ami -s prod
atmos packer inspect my-ami -s prod

Single File Mode (Backward Compatible)​

If you prefer to use a single template file, you can still specify it explicitly:

# Stack configuration with explicit template
components:
  packer:
    my-ami:
      settings:
        packer:
          template: main.pkr.hcl  # Use specific file
      vars:
        region: us-east-1

Or use the --template flag:

atmos packer build my-ami -s prod --template main.pkr.hcl

Examples​

Multi-File Component Structure​

# components/packer/my-ami/variables.pkr.hcl
variable "region" {
  type        = string
  description = "AWS region to build the AMI"
}

variable "instance_type" {
  type        = string
  default     = "t3.medium"
  description = "EC2 instance type for the builder"
}

variable "ami_name" {
  type        = string
  description = "Name for the resulting AMI"
}

# components/packer/my-ami/main.pkr.hcl
packer {
  required_plugins {
    amazon = {
      version = ">= 1.2.0"
      source  = "github.com/hashicorp/amazon"
    }
  }
}

source "amazon-ebs" "base" {
  region        = var.region
  instance_type = var.instance_type
  ami_name      = "${var.ami_name}-{{timestamp}}"
  # ... other settings
}

build {
  sources = ["source.amazon-ebs.base"]
  # ... provisioners
}

Validating Multi-File Components​

# Validate all files in the component directory
atmos packer validate my-ami -s prod

# Inspect the combined template
atmos packer inspect my-ami -s prod

Backward Compatibility​

All existing configurations continue to work unchanged:

• Components with explicit settings.packer.template use the specified file
• The --template flag overrides both the default and settings values
• Single-file components work exactly as before

Documentation​

For more details, see:

• Packer Components
• Packer Build Command
• Packer Usage

What Changed​

Two new command aliases make discoverability more intuitive:

• atmos vendor list is now an alias for atmos list vendor
• atmos workflow list is now an alias for atmos list workflows

Both command forms are equivalent and share the same flags, completions, and output.

Why This Matters​

Users naturally expect list commands under the parent command (e.g., atmos vendor list), while Atmos organizes all list commands under atmos list. This bidirectional aliasing follows the same pattern as atmos list themes and atmos theme list.

How to Use It​

Both forms work identically:

# These are equivalent
atmos vendor list
atmos list vendor

# These are equivalent
atmos workflow list
atmos list workflows

# All flags work the same
atmos vendor list --format json
atmos workflow list --format csv

What Changed​

Building on the declarative file generation feature, this release adds several improvements:

• Interactive prompts for component and stack selection when arguments are missing
• Cross-provisioner support for helmfile and packer (not just terraform)
• Idempotent generation that only writes files when content changes
• Deterministic output with sorted map keys for reproducible generation
• JIT component creation with auto-generation running BEFORE path validation

$ atmos terraform generate files
? Choose a component
  > vpc
    eks-cluster
    rds-aurora
? Choose a stack
  > ue2-dev
    ue2-prod

Why This Matters​

Discoverability​

When working with unfamiliar infrastructure, you may not know which components have file generation configured. Interactive prompts let you explore what's available without digging through YAML files.

Cross-Provisioner Consistency​

Teams using helmfile or packer alongside terraform can now use the same file generation patterns across all provisioners:

# atmos.yaml
components:
  terraform:
    auto_generate_files: true
  helmfile:
    auto_generate_files: true
  packer:
    auto_generate_files: true

Idempotent Operations​

File generation now compares existing content before writing. This means:

• No unnecessary file modifications
• Cleaner git diffs
• Faster execution when files haven't changed

How It Works​

Interactive Selection​

When you omit the component or stack argument in an interactive terminal, Atmos prompts for selection:

$ atmos terraform generate files
? Choose a component
  > vpc
i Selected component `vpc`
? Choose a stack
  > ue2-dev
i Selected stack `ue2-dev`

Generating files for component `vpc` in stack `ue2-dev`...

JIT Component Creation​

With auto_generate_files: true, files are generated BEFORE path validation during component execution. This enables just-in-time component creation where the generated files can create the component directory itself.

Summary Output​

After generation, you see exactly what changed:

✓ Generated file: locals.tf
✓ Generated file: context.json
i Summary: 2 files generated (2 created, 0 updated, 0 unchanged)

Disabling Interactive Prompts​

For scripts and automation, disable prompts the same way as other interactive commands:

# Via flag
atmos terraform generate files vpc -s ue2-dev --interactive=false

# Via environment variable
export ATMOS_INTERACTIVE=false

Get Involved​

• Review the generate files documentation for configuration options
• See the example in examples/generate-files/ demonstrating the feature
• Share feedback on GitHub

What Changed​

Previously, automatic backend provisioning required running atmos terraform backend create explicitly before initializing Terraform. Now, backends are provisioned automatically when you run any Terraform command that triggers initialization:

# Before: Two commands required
atmos terraform backend create vpc -s dev
atmos terraform plan vpc -s dev

# After: Single command - backend auto-provisioned on init
atmos terraform plan vpc -s dev
# ⠋ Provisioning S3 backend `my-terraform-state` for `vpc` in stack `dev`...
# ✓ Provisioned S3 backend `my-terraform-state` for `vpc` in stack `dev`
# ... terraform init continues automatically

How It Works​

When provision.backend.enabled: true is configured, Atmos registers a hook that runs before terraform init:

1. Check if enabled - Silent skip if provision.backend.enabled is not true
2. Check if exists - Silent skip if backend already exists (idempotent)
3. Provision with feedback - Create backend with spinner showing progress
4. Continue init - Terraform initialization proceeds automatically

This behavior is completely opt-in. Without the provision configuration, nothing changes.

Configuration​

The configuration remains the same - just add provision.backend.enabled: true:

components:
  terraform:
    vpc:
      backend_type: s3
      backend:
        bucket: my-terraform-state
        key: vpc/terraform.tfstate
        region: us-east-1
      provision:
        backend:
          enabled: true

You can also set this at the global terraform level for all components:

terraform:
  provision:
    backend:
      enabled: true

components:
  terraform:
    vpc:
      # Inherits provision.backend.enabled: true from above
      backend_type: s3
      backend:
        bucket: my-terraform-state
        key: vpc/terraform.tfstate
        region: us-east-1

UX Improvements​

This release also includes improved output formatting:

• Spinner feedback - Visual progress indicator during provisioning
• Consolidated messages - Single line output instead of multiple status messages
• Backend type and name - Shows backend type (S3, GCS, etc.) and resource name (bucket)
• Markdown-friendly formatting - Backticks around names render correctly in terminals

Idempotent Behavior​

The auto-provisioning is idempotent:

• First run: Backend is created with spinner feedback
• Subsequent runs: Silent skip (backend already exists)
• After Terraform import: Safe to leave enabled - no conflicts

This means you can safely leave provision.backend.enabled: true in your configuration permanently.

Explicit Command Still Available​

The explicit backend create command remains available for CI/CD pipelines or manual provisioning:

atmos terraform backend create vpc -s dev

Getting Started​

Enable automatic backend provisioning in your stack configuration and run any Terraform command:

atmos terraform plan vpc -s dev

That's it - no separate provisioning step required.

For more details, see our original announcement and CLI documentation.

What Changed​

Four UX improvements to the source provisioner:

1. Auto-provisioning spinner: When components are automatically vendored on first use, you now see a spinner with progress instead of static messages
2. Interactive delete confirmation: Running atmos terraform source delete without --force now prompts for confirmation instead of erroring
3. Delete operation spinner: Deletion shows a spinner during the operation for consistent feedback
4. Interactive stack selection: All source commands (pull, delete, describe, list) now prompt for stack selection when --stack is omitted

Why This Matters​

These changes align the source provisioner with UX patterns used elsewhere in Atmos:

# Before: Static messages during auto-provisioning
ℹ Auto-provisioning source for component 'myapp'
✓ Auto-provisioned source to .workdir/terraform/dev-myapp

# After: Spinner shows progress
⠋ Auto-provisioning source for 'myapp'
✓ Auto-provisioned source to .workdir/terraform/dev-myapp

# Before: Delete required --force or failed
$ atmos terraform source delete myapp --stack dev
Error: --force flag required for safety

# After: Interactive confirmation when --force omitted
$ atmos terraform source delete myapp --stack dev
? Delete directory: .workdir/terraform/dev-myapp? [Yes!/No.]
⠋ Deleting .workdir/terraform/dev-myapp
✓ Deleted .workdir/terraform/dev-myapp

# Before: Required --stack flag or error
$ atmos terraform source pull myapp
Error: --stack flag is required

# After: Interactive stack selection when --stack omitted
$ atmos terraform source pull myapp
? Choose a stack
  dev
> prod
  staging
ℹ Selected stack `prod`
⠋ Provisioning source for 'myapp'
✓ Provisioned source to components/terraform/myapp

How to Use It​

No configuration changes needed. The improvements apply automatically:

• With TTY: Get interactive prompts and spinners
• Without TTY (CI/scripts): Use --force to skip confirmation, spinners degrade gracefully
• Force flag: Still available for scripted workflows: atmos terraform source delete myapp --stack dev --force

What Changed​

Simplified Query Syntax for List Commands​

The atmos list components command now supports a simplified query syntax that makes filtering components more intuitive:

# Filter by stack pattern
atmos list components plat-ue2-dev

# Filter by component name
atmos list components vpc

# Combine filters
atmos list components vpc plat-ue2-dev

This replaces the need for verbose --stack flags in many common cases.

New atmos list aliases Subcommand​

View all command aliases—both built-in and user-configured:

atmos list aliases

This command shows:

• Built-in aliases: Native command shortcuts (e.g., tf → terraform, hf → helmfile)
• Configured aliases: User-defined shortcuts from your atmos.yaml

The output includes a "Type" column so you can easily distinguish between the two, helping you discover all available shortcuts in your project.

Multi-Tool Installation​

Install multiple tools in a single command:

atmos toolchain install opentofu tflint kubectl helm

Previously, each tool required a separate atmos toolchain install invocation. Now you can batch installations with a progress summary.

Why This Matters​

• Faster Workflows: Query syntax reduces typing for common list operations
• Better Discoverability: The aliases command helps teams discover configured shortcuts
• Streamlined Setup: Multi-tool installation speeds up environment bootstrapping

How to Use It​

Update to the latest version of Atmos:

atmos version install latest

Then try the new features:

# Explore the simplified query syntax
atmos list components --help

# View your configured aliases
atmos list aliases

# Install your toolchain in one command
atmos toolchain install opentofu terraform-docs tflint

What Changed​

The atmos list components command behavior has been restored to its original intent:

• list components - Shows unique component definitions (deduplicated across all stacks)
• list instances - Shows all component instances (one entry per component+stack pair)

Previously, both commands were returning the same data (component instances), which was confusing.

New: Filter Components by Stack​

You can now filter which stacks to consider when listing unique components using the --stack flag with glob patterns:

# List components that exist in any dev stack
atmos list components --stack "*-dev"

# List components in a specific environment
atmos list components --stack "plat-ue2-*"

# List components across all production stacks
atmos list components --stack "*-prod"

This is useful when you want to see what components are defined for a particular environment or stage without seeing the full list across all stacks.

New Configuration Namespace​

We've introduced a cleaner configuration structure for list commands with separate settings for list components and list instances:

# atmos.yaml
list:
  # Configuration for "atmos list components"
  # Shows unique component definitions (deduplicated)
  components:
    format: table
    columns:
      - name: Component
        value: "{{ .component }}"
      - name: Type
        value: "{{ .type }}"
      - name: Stacks
        value: "{{ .stack_count }}"

  # Configuration for "atmos list instances"
  # Shows component instances (one per component+stack pair)
  instances:
    format: table
    columns:
      - name: Stack
        value: "{{ .stack }}"
      - name: Component
        value: "{{ .component }}"
      - name: Type
        value: "{{ .type }}"
      - name: Tenant
        value: "{{ .vars.tenant }}"
      - name: Environment
        value: "{{ .vars.environment }}"

Available Fields​

For list components (unique component fields):

• {{ .component }} - Component name
• {{ .type }} - Component type (terraform, helmfile, packer)
• {{ .stack_count }} - Number of stacks using this component
• {{ .component_folder }} - Path to component folder

For list instances (per-instance fields):

• All unique component fields above, plus:
• {{ .stack }} - Stack name
• {{ .vars.* }} - Any variable from the component (tenant, environment, stage, region, etc.)
• {{ .status }} - Component status indicator

Backward Compatibility​

Existing configurations using components.list.columns continue to work for list instances. The precedence is:

For list instances:

1. --columns CLI flag
2. list.instances.columns (new)
3. components.list.columns (deprecated, backward compat)
4. Default columns

For list components:

1. --columns CLI flag
2. list.components.columns (new)
3. Default columns (Component, Type, Stacks)

Note: The old components.list.columns does not fall back for list components because those columns were designed for per-instance data (with stack-specific fields).

Example Output​

atmos list components now shows unique components:

Component             Type        Stacks
vpc                   terraform   6
vpc-flow-logs-bucket  terraform   6

atmos list components --stack "*-dev" filters to dev stacks:

Component             Type        Stacks
vpc                   terraform   2
vpc-flow-logs-bucket  terraform   2

atmos list instances continues to show all instances:

Stack           Component             Type        ...
plat-ue2-dev    vpc                   terraform   ...
plat-ue2-dev    vpc-flow-logs-bucket  terraform   ...
plat-ue2-prod   vpc                   terraform   ...
...

Migration​

Update your atmos.yaml from:

components:
  list:
    columns: [...]

To:

list:
  instances:
    columns: [...]

And optionally add a list.components section to customize the unique components output.

How It Works​

When you open the search dialog (press / or Cmd+K), you can seamlessly switch between traditional keyword search and a chat-style assistant that understands your questions.

Key features:

• Natural language queries - Ask questions like "How do I configure AWS SSO authentication?" or "What's the difference between stacks and components?"
• Contextual answers - Responses are generated from the actual documentation content, not generic AI knowledge
• Source citations - Every answer includes links to the specific documentation pages it drew from
• Seamless experience - Switch between keyword search and AI assistant without leaving the search dialog.

Under the Hood​

Ask AI uses Algolia's integration with large language models (LLMs) to understand your questions and find relevant information from the indexed documentation. The assistant is specifically trained on Atmos documentation, so it understands:

• Atmos CLI commands and their flags
• Stack configuration patterns and YAML syntax
• Authentication providers and identity management
• Workflows, custom commands, and extensibility patterns
• Design patterns and best practices

Try It Now​

Visit atmos.tools and press / or Cmd+K to open the search dialog. Try asking questions like:

• "How do I set up AWS SSO with Atmos?"
• "What is the difference between imports and inheritance?"
• "How do I create a custom workflow?"
• "What YAML functions are available?"

The AI assistant will provide detailed answers with direct links to the relevant documentation pages.

Technical Details​

This feature is enabled by upgrading to Docusaurus 3.9.2 and DocSearch v4, which adds native support for Algolia's Ask AI feature. The assistant is configured with an understanding of Atmos as a DevOps and cloud automation tool, ensuring responses are relevant and technically accurate.

Get Involved​

Have feedback on Ask AI? We'd love to hear how it's helping you navigate the documentation:

• Open an issue for bugs or feature requests
• Join our Slack to discuss with the community
• Star the repo if you find Atmos helpful

What's New​

Experimental features in Atmos are now clearly marked and controllable. The new settings.experimental configuration option lets you choose how Atmos handles experimental commands:

• warn (default) — Show a notification when running experimental commands, then continue
• silence — Run experimental commands without any notification
• disable — Block experimental commands entirely
• error — Show notification and exit with an error code

CLI Visibility​

Experimental commands are now clearly marked in help output with an [EXPERIMENTAL] badge:

AVAILABLE COMMANDS

      devcontainer [command] [EXPERIMENTAL]  Manage development containers
      terraform                              Execute terraform commands
      toolchain [command] [EXPERIMENTAL]     Manage CLI tool versions

When you run --help on an experimental command, you'll see a prominent badge at the top:

[EXPERIMENTAL]

Manage development containers with full lifecycle support.

Configuration​

Control experimental features in atmos.yaml:

settings:
  # Control experimental feature handling
  # Values: "silence", "disable", "warn" (default), "error"
  experimental: warn

Or via environment variable:

export ATMOS_EXPERIMENTAL=disable

Current Experimental Features​

The following features are currently marked as experimental:

Use Cases​

Development Environment​

For local development where you want to experiment with new features:

settings:
  experimental: warn  # See warnings but continue working

CI/CD Pipeline​

For continuous integration where you want stability:

settings:
  experimental: disable  # Block experimental commands in CI

Production Environment​

For production where experimental features must be explicitly enabled:

settings:
  experimental: error  # Require explicit opt-in

Why This Matters​

As Atmos continues to evolve, we're adding powerful new capabilities like devcontainers, toolchain management, and advanced Terraform features. These features need real-world testing before they're considered stable.

The experimental feature flag gives you:

• Clear visibility — Know immediately when you're using an experimental feature
• Granular control — Choose how to handle experimental features per environment
• Safe exploration — Try new features locally while keeping CI stable
• Predictable behavior — Same configuration works identically across environments

Documentation​

For complete documentation on experimental features and configuration options, see:

• Experimental Features Configuration
• Settings Reference

The Problem​

When using file-scoped locals as documented, templates referencing locals were not being resolved:

# stacks/prod.yaml
locals:
  namespace: acme
  environment: prod
  name_prefix: "{{ .locals.namespace }}-{{ .locals.environment }}"

components:
  terraform:
    myapp:
      vars:
        name: "{{ .locals.name_prefix }}-myapp"
        stage: "{{ .locals.environment }}"

Running atmos describe component showed raw template strings instead of resolved values:

# Before fix - templates not resolved
vars:
  name: "{{ .locals.name_prefix }}-myapp"
  stage: "{{ .locals.environment }}"

The Fix​

Atmos now correctly resolves locals before template processing. The same configuration now produces the expected output:

# After fix - templates resolved correctly
vars:
  name: "acme-prod-myapp"
  stage: "prod"

What Changed​

1. Locals extraction - Raw YAML is now parsed to extract locals: sections before template processing
2. Template context - Resolved locals are added to the template context so {{ .locals.* }} references work
3. Section override tracking - Section-specific locals (in terraform:, helmfile:, packer:) correctly override global locals
4. Component-level locals - Components can now define their own locals: section that inherits from base components

New Command: atmos describe locals​

A new command has been added to help inspect and debug locals configurations:

# Show locals for a specific stack (using file path)
atmos describe locals --stack deploy/dev

# Show locals for a specific stack (using logical stack name from atmos.yaml)
atmos describe locals --stack prod-us-east-1

# Show locals available to a specific component in a stack
atmos describe locals vpc -s prod

# Output as JSON
atmos describe locals -s dev --format json

# Write to file
atmos describe locals -s dev --file locals.yaml

Note: The --stack flag is required. Locals are file-scoped, so a specific stack must be specified.

The --stack flag accepts either a stack manifest file path (e.g., deploy/dev) or a logical stack name derived from your atmos.yaml naming pattern (e.g., prod-us-east-1). Both resolve to the same underlying file, and locals are returned from that file only.

Component-Specific Locals​

When specifying a component with the --stack flag, the command shows the merged locals that would be available to that component during template processing. This includes global locals, section-specific locals (for the component's type), and component-level locals (including inherited from base components):

atmos describe locals vpc -s prod

components:
  terraform:
    vpc:
      locals:
        namespace: acme
        environment: prod
        backend_bucket: acme-prod-tfstate

The output uses Atmos schema format, matching the structure of stack manifest files.

Stack-Level Output​

Without a component argument, the output is in direct stack manifest format:

locals:
  namespace: acme
  environment: dev
  name_prefix: acme-dev
terraform:
  locals:
    backend_bucket: acme-dev-tfstate

• locals - Global locals defined at root level of the stack file
• terraform/helmfile/packer - Section-specific locals nested under { locals: } (only shown if defined)

The output is in direct stack manifest format - it can be redirected to a file and used as valid YAML (e.g., atmos describe locals -s dev --file locals.yaml).

Section-Specific Locals​

Locals can be defined at multiple levels, with later scopes overriding earlier ones:

# Global locals
locals:
  namespace: "global-acme"

terraform:
  # Terraform-scope locals override global
  locals:
    namespace: "terraform-acme"
    backend_bucket: "{{ .locals.namespace }}-tfstate"

components:
  terraform:
    myapp:
      vars:
        # Uses terraform-scope value: "terraform-acme-tfstate"
        bucket: "{{ .locals.backend_bucket }}"

Features That Work​

All documented locals features now function correctly:

Component-Level Locals with Inheritance​

components:
  terraform:
    vpc/base:
      locals:
        vpc_type: "standard"
        cidr_prefix: "10.0"

    vpc/prod:
      metadata:
        inherits:
          - vpc/base
      locals:
        vpc_type: "production"  # Overrides base
      vars:
        cidr: "{{ .locals.cidr_prefix }}.0.0/16"  # Inherited from base

Locals Referencing Other Locals​

locals:
  namespace: acme
  environment: prod
  # Resolved in dependency order
  name_prefix: "{{ .locals.namespace }}-{{ .locals.environment }}"
  full_name: "{{ .locals.name_prefix }}-us-east-1"

Circular Dependency Detection​

Atmos detects circular dependencies and logs them gracefully:

# This triggers a circular dependency warning
locals:
  a: "{{ .locals.b }}"
  b: "{{ .locals.a }}"

Complex Values​

Maps and nested structures work as expected:

locals:
  common_tags:
    Environment: "{{ .locals.environment }}"
    Namespace: "{{ .locals.namespace }}"

components:
  terraform:
    vpc:
      vars:
        tags: "{{ .locals.common_tags }}"

Supported Scopes​

Locals can be defined at three levels:

# Global locals (root level) - available throughout the file
locals:
  namespace: acme
  environment: prod

# Section-level locals (terraform/helmfile/packer) - inherit from global
terraform:
  locals:
    backend_bucket: "{{ .locals.namespace }}-{{ .locals.environment }}-tfstate"

components:
  terraform:
    vpc:
      # Component-level locals - inherit from global and section, plus base components
      locals:
        vpc_type: "production"
      vars:
        # Uses merged locals (global + terraform section + component)
        bucket: "{{ .locals.backend_bucket }}"
        type: "{{ .locals.vpc_type }}"

Component-Level Locals Inheritance​

Component-level locals support inheritance from base components via metadata.inherits or component attribute, similar to how vars work:

components:
  terraform:
    vpc/base:
      metadata:
        type: abstract
      locals:
        vpc_type: "standard"
        cidr_prefix: "10.0"

    vpc/prod:
      metadata:
        inherits:
          - vpc/base
      locals:
        # Overrides base component's vpc_type
        vpc_type: "production"
      vars:
        # Uses inherited cidr_prefix from base, overridden vpc_type
        cidr: "{{ .locals.cidr_prefix }}.0.0/16"
        name: "{{ .locals.vpc_type }}-vpc"

Full locals resolution order for a component:

Global Locals → Section Locals → Base Component Locals → Component Locals

Note: File-scoped locals (global and section-level) do NOT inherit across file boundaries. Only component-level locals inherit from base components.

Upgrade​

Upgrade Atmos to get this fix. No configuration changes are required. Your existing locals: definitions will automatically start working.

import:
  - path: catalog/helm-values
    skip_templates_processing: true

# View locals for a specific stack
atmos describe locals -s prod

# Verify locals are resolving correctly in component output
atmos describe component myapp -s prod --format yaml

References​

• GitHub Issue #1933
• File-Scoped Locals Documentation
• Original Feature Announcement

What Changed​

Single Identity Rule​

Each stack now has exactly ONE valid identifier based on this precedence:

1. name (highest) - Explicit name from stack manifest
2. name_template - Go template from atmos.yaml
3. name_pattern - Token pattern from atmos.yaml
4. Filename (lowest) - Basename of the stack file

Previously, a stack might respond to multiple identifiers (e.g., both the filename and a generated name). Now, only the highest-priority identifier is valid.

Zero-Config Stack Naming​

When no name, name_template, or name_pattern is configured, stacks are identified by their filename. This enables newcomers to start using Atmos immediately without any naming configuration.

Why This Matters​

For Newcomers​

Getting started with Atmos is now simpler. Create a stack file and reference it by filename:

# stacks/prod.yaml
components:
  terraform:
    vpc:
      vars:
        cidr: "10.0.0.0/16"

# Just works - no naming configuration required
atmos terraform plan vpc -s prod

For Advanced Users​

The single identity rule prevents confusion. If you have:

# stacks/legacy-prod.yaml
name: "my-legacy-prod-stack"

Only atmos terraform plan vpc -s my-legacy-prod-stack works. Using -s legacy-prod correctly returns an error because that's not the canonical name.

Migration Notes​

If you were using both the filename and a generated name to reference the same stack, you must now use only the canonical name. Check which identifier has highest precedence:

• Stack has name field? Use that name.
• name_template or name_pattern configured? Use the generated name.
• Neither? Use the filename.

Related​

• Stack Manifest Name Override
• Stack Names Documentation

The Problem​

When workspaces_enabled: false is set in atmos.yaml, Atmos sets the workspace name to default. However, Terraform stores state differently for the default workspace compared to named workspaces:

Atmos was incorrectly looking for state at the named workspace path even when using the default workspace. For example:

# atmos.yaml
components:
  terraform:
    workspaces_enabled: false  # Uses "default" workspace

# Stack manifest
components:
  terraform:
    my-component:
      vars:
        vpc_id: !terraform.state vpc output_id  # Failed to find state!

The !terraform.state function would look for state at workspace_key_prefix/default/key (S3) or terraform.tfstate.d/default/terraform.tfstate (local) instead of the correct location.

The Fix​

Atmos now correctly handles the default workspace for all backend types:

• S3 backend: Uses <key> directly instead of <workspace_key_prefix>/default/<key>
• Local backend: Uses terraform.tfstate instead of terraform.tfstate.d/default/terraform.tfstate
• Azure backend: Already worked correctly

Example​

With workspaces disabled, the !terraform.state function now works as expected:

# atmos.yaml
components:
  terraform:
    workspaces_enabled: false

# Stack manifest
components:
  terraform:
    networking:
      metadata:
        component: vpc
      vars:
        cidr: "10.0.0.0/16"

    application:
      metadata:
        component: app
      vars:
        # Now correctly reads from terraform.tfstate (not terraform.tfstate.d/default/terraform.tfstate)
        vpc_id: !terraform.state networking vpc_id
        subnet_ids: !terraform.state networking private_subnet_ids

Upgrade​

Upgrade Atmos to get this fix. No configuration changes are required. The !terraform.state function will automatically use the correct state file paths based on your workspace configuration.

References​

• GitHub Issue #1920
• Terraform S3 Backend Documentation
• Terraform Local Backend Documentation
• Terraform Azure Backend Documentation
• Terraform GCS Backend Documentation