Why This Matters​

Reviewing AWS security findings today means navigating Security Hub, cross-referencing resources with Terraform code, and manually figuring out which stack configuration caused the issue. This is slow and requires deep AWS + Terraform expertise.

With atmos aws security analyze, one command replaces that entire workflow:

atmos aws security analyze --stack prod-us-east-1

The command fetches findings, maps them to your Atmos components via resource tags, and shows which code manages each affected resource. Add --ai for AI-powered remediation with specific code changes and deploy commands.

Quick Start​

aws:
  security:
    enabled: true
    identity: "security-readonly"  # Atmos Auth identity → Security Hub account
    region: "us-east-2"            # Security Hub aggregation region
    tag_mapping:
      stack_tag: "atmos:stack"
      component_tag: "atmos:component"

# Authenticate and analyze
atmos auth login
atmos aws security analyze
atmos aws security analyze --ai  # With AI remediation

What You Get​

Without --ai — findings with component mapping:

## CRITICAL Findings (2)

### 1. S3 bucket without encryption

| Field | Value |
|-------|-------|
| **Severity** | CRITICAL |
| **Source** | security-hub (CIS-1.4) |
| **Resource** | `arn:aws:s3:::my-bucket` |
| **Component** | s3-bucket |
| **Stack** | prod-us-east-1 |
| **Confidence** | exact |

With --ai — adds structured remediation:

#### Remediation

**Root Cause:** The S3 bucket was provisioned without enabling versioning.

**Steps:**
1. Add versioning_enabled variable to the stack configuration
2. Apply the change

**Stack Changes:**
  vars:
    versioning_enabled: true

**Deploy:** `atmos terraform apply s3-bucket -s prod-us-east-1`

**Risk:** low

Key Features​

• Finding-to-code mapping — traces AWS resources back to Atmos components via tags or naming heuristics
• Atmos Auth integration — identity field targets the Security Hub delegated admin account
• Multi-turn AI analysis — API providers can call atmos_describe_component, read_component_file to gather context before generating remediation
• CLI provider support — Claude Code and Codex CLI fall back to enriched single-prompt mode
• Compliance reports — atmos aws compliance report --framework cis-aws for framework-specific posture
• Four output formats — Markdown (terminal), JSON (CI/CD), YAML (config), CSV (spreadsheets)
• Structured schema — every output follows the same schema regardless of AI provider

Commands​

# All findings across all stacks
atmos aws security analyze

# Filter by stack and/or component
atmos aws security analyze --stack prod-us-east-1
atmos aws security analyze --stack prod-us-east-1 --component vpc

# Filter by severity or source
atmos aws security analyze --severity critical,high --source guardduty

# AI-powered remediation (deduplicates findings, retries on errors)
atmos aws security analyze --stack prod-us-east-1 --ai

# Save to file in any format
atmos aws security analyze --format json --file findings.json
atmos aws security analyze --stack prod-us-east-1 --file report.md
atmos aws security analyze --format csv --file audit.csv

# Compliance reports
atmos aws compliance report --framework cis-aws
atmos aws compliance report --framework pci-dss --format json --file compliance.json

# Override identity or region at runtime
atmos aws security analyze --identity security-admin --region us-west-2

See It in Action​

Tested against a multi-account AWS organization (11 accounts, Security Hub delegated admin, 500 findings fetched, 97% mapped to Atmos components).

Without --ai — findings mapped to components:

$ atmos aws security analyze --stack plat-use2-dev --component rds/example

ℹ Fetching security findings...
ℹ Mapping 500 findings to Atmos components...
ℹ Filtered to 4 findings matching stack="plat-use2-dev" component="rds/example"

# Security Report: plat-use2-dev / rds/example

Findings: 4 (1 CRITICAL, 3 HIGH)

## CRITICAL Findings (1)

### 1. Security groups should not allow unrestricted access to ports with high risk

| Field          | Value                                                        |
|----------------|--------------------------------------------------------------|
| **Severity**   | CRITICAL                                                     |
| **Source**     | security-hub (aws-foundational-security-best-practices/1.0)  |
| **Resource**   | arn:aws:ec2:us-east-2:***:security-group/sg-***              |
| **Component**  | rds/example                                                  |
| **Stack**      | plat-use2-dev                                                |
| **Confidence** | exact                                                        |
| **Mapped By**  | finding-tag                                                  |

Resource Tags:

• atmos_stack = plat-use2-dev
• atmos_component = rds/example
• terraform_component = rds
• terraform_workspace = plat-use2-dev-rds-example
• Name = acme-plat-use2-dev-example-postgres-db
• Namespace = acme
• Tenant = plat
• Environment = use2
• Stage = dev

## HIGH Findings (3)
1. Security groups should only allow unrestricted incoming traffic for authorized ports
2. Security groups should not allow ingress from 0.0.0.0/0 to port 22
3. Security groups should not allow ingress from 0.0.0.0/0 to port 3389

## Summary
| Severity  | Count | Mapped | Unmapped |
|-----------|-------|--------|----------|
| CRITICAL  | 1     | 1      | 0        |
| HIGH      | 3     | 3      | 0        |
| **Total** | **4** | **4**  | **0**    |

With --ai — the AI reads the actual Terraform source and stack config via tools, detects drift, and generates targeted remediation:

$ atmos aws security analyze --stack plat-use2-dev --component rds/example --ai

ℹ Analyzing findings with AI...

✓ AI analysis complete — Security Analysis: rds/example in plat-use2-dev

## Summary

The analysis surfaced 4 findings against a single security group — all mapped
with exact confidence to this component via Atmos tags.

| Severity    | Count |
|-------------|-------|
| 🔴 CRITICAL | 1     |
| 🟠 HIGH     | 3     |

## Findings Breakdown

### 🟠 Finding 1 — EC2.18: Unrestricted Ingress on Unauthorized Port (HIGH)

Standard: AWS Foundational Security Best Practices v1.0.0

Port 5432 (PostgreSQL) is open to 0.0.0.0/0. The likely cause is
allowed_cidr_blocks being set to an overly permissive value — potentially
from commented-out lines in catalog/rds/defaults.yaml that were activated
at some point.

Fix: Set in catalog/rds/example.yaml:
    allowed_cidr_blocks: []
    publicly_accessible: false

### 🟠 Finding 2 — EC2.13: Unrestricted Ingress on Port 22/SSH (HIGH)

Standard: CIS AWS Foundations Benchmark v1.2.0

⚠️ This is anomalous — port 22 has no business being on an RDS security
group. This strongly suggests an out-of-band manual change was made directly
in the AWS Console, or a referenced SG in associate_security_group_ids
carries a port-22 rule.

Fix:
1. Immediately audit and manually remove the port-22 rule in the AWS Console
2. Audit any SGs referenced via associate_security_group_ids / security_group_ids
3. Re-apply via Terraform to restore IaC control and eliminate drift

## Root Cause (Common Thread)

Both findings stem from the same security group and share a root cause:
var.allowed_cidr_blocks being set too permissively, compounded by possible
out-of-band drift. The cloudposse/rds/aws module internally creates and
manages SG ingress rules based on this variable.

## Priority Actions

1. Immediately remove the port-22 inbound rule manually — this is likely
   out-of-band drift and poses direct unauthorized access risk

2. Update catalog/rds/example.yaml to explicitly enforce safe defaults:
     allowed_cidr_blocks: []
     publicly_accessible: false
     associate_security_group_ids: []
     use_private_subnets: true

3. Add Terraform validation guards to rds-variables.tf to prevent future
   regressions:
     validation {
       condition     = !contains(var.allowed_cidr_blocks, "0.0.0.0/0")
                       && !contains(var.allowed_cidr_blocks, "::/0")
       error_message = "allowed_cidr_blocks must not contain 0.0.0.0/0 or ::/0."
     }

4. Clean up catalog/rds/defaults.yaml — permanently remove (don't just
   comment out) any lines with 0.0.0.0/0 or publicly_accessible: true

5. Plan then apply:
     atmos terraform plan rds/example -s plat-use2-dev
     atmos terraform apply rds/example -s plat-use2-dev

## Risk Assessment

| Finding              | Risk   | Note                                              |
|----------------------|--------|---------------------------------------------------|
| EC2.18 (port 5432)   | Medium | Removing rule breaks direct internet connections  |
|                      |        | to DB; client SG-based connections are unaffected |
| EC2.13 (port 22/SSH) | Low    | No RDS traffic should depend on SSH; removing     |
|                      |        | has no expected legitimate impact                 |

The AI used multi-turn tools (atmos_describe_component, read_component_file) to read the actual Terraform source and stack config, detected that port 22 on an RDS security group is anomalous (likely AWS Console drift), identified the common root cause in allowed_cidr_blocks, and generated targeted remediation with Terraform validation guards to prevent future regressions. Duplicate findings are deduplicated before AI analysis — one call covers all related findings.

Compliance report — framework-specific posture scoring:

$ atmos aws compliance report

# Compliance Report: CIS AWS Foundations Benchmark

## Score: 35/42 Controls Passing (83%)

### Failing Controls

| Control      | Title                                                                    | Severity |
|--------------|--------------------------------------------------------------------------|----------|
| Config.1     | AWS Config should be enabled with service-linked role                    | CRITICAL |
| EC2.14       | Security groups should not allow ingress from 0.0.0.0/0 to port 3389     | HIGH     |
| EC2.13       | Security groups should not allow ingress from 0.0.0.0/0 to port 22       | HIGH     |
| S3.1         | S3 buckets should have block public access settings enabled              | MEDIUM   |
| EC2.6        | VPC flow logging should be enabled in all VPCs                           | MEDIUM   |
| IAM.17       | Ensure IAM password policy expires passwords within 90 days              | LOW      |
| CloudTrail.7 | Ensure S3 bucket access logging is enabled on CloudTrail S3 bucket       | LOW      |

Compliance with --ai — adds prioritized remediation guidance:

$ atmos aws compliance report --ai

✓ AI analysis complete — CIS Foundations Benchmark

## Overall Status: 🟡 83% Compliant (35/42 controls passing)

## 🚨 Priority Issues (Fix First)

### CRITICAL
| Control  | Issue                                   | Action                               |
|----------|-----------------------------------------|--------------------------------------|
| Config.1 | AWS Config not enabled or missing role  | Enable in all regions, attach role   |

### HIGH
| Control | Issue                             | Action                                  |
|---------|-----------------------------------|-----------------------------------------|
| EC2.14  | RDP (port 3389) open to 0.0.0.0/0 | Restrict to known IP ranges or VPN      |
| EC2.13  | SSH (port 22) open to 0.0.0.0/0   | Use SSM Session Manager instead of SSH  |

⚠️ Open SSH/RDP to the world is a common attack vector.

## 🟠 Medium Priority
• S3.1 — Enable S3 Block Public Access at the account level
• EC2.6 — Enable VPC Flow Logs for all VPCs

## 🟢 Low Priority
• IAM.17 — Set IAM password policy MaxPasswordAge to ≤ 90 days
• CloudTrail.7 — Enable S3 access logging on CloudTrail bucket

## Recommended Next Steps
1. Lock down security groups for ports 22/3389
2. Enable AWS Config — also helps detect future drift
3. Run `atmos terraform apply` on security-groups, vpc, config components
4. Re-run this report after remediation to verify score improves

Try It​

Learn More​

• Security Configuration
• Security Analyze Command
• Compliance Report Command
• Atmos Auth

Why This Matters​

Until now, using Atmos AI required purchasing API tokens from a provider and configuring keys. Many developers already have Claude Code or Codex installed with active subscriptions (Claude Max, ChatGPT Pro, or Gemini's free tier). CLI providers let you reuse that investment:

• No API keys — the CLI tool handles auth via its own subscription
• No per-token billing — included in your existing plan
• Full MCP support — Claude Code and Codex CLI can use all your configured MCP servers

Quick Start​

ai:
  enabled: true
  default_provider: "claude-code"  # or "codex-cli" or "gemini-cli"
  providers:
    claude-code:
      max_turns: 10

brew install --cask claude-code && claude auth login
atmos ai ask "What did we spend on EC2 last month?"

That's it. Atmos detects the binary, generates an MCP config with auth wrapping, and passes everything to Claude Code. You get answers from real AWS data using your subscription.

Available CLI Providers​

All three providers work for prompt-only queries. For MCP-enabled workflows (AWS billing, security, IAM, etc.), use Claude Code or Codex CLI.

MCP Pass-Through​

When mcp.servers is configured in atmos.yaml, Atmos automatically passes MCP servers to the CLI tool. Each provider uses its native config format:

• Claude Code — temp .mcp.json via --mcp-config
• Codex CLI — ~/.codex/config.toml (backup/restore after exit)
• Gemini CLI — .gemini/settings.json in the current working directory

Auth-requiring servers are wrapped with atmos auth exec -i <identity>. Toolchain PATH and ATMOS_* env vars are injected automatically.

See It in Action​

Outputs below are from a production setup with 8 AWS MCP servers configured.

Claude Code — Security Posture​

$ atmos ai ask "What is our security posture in us-east-2 region?"

ℹ MCP servers configured: 8 (config: /tmp/atmos-mcp-config.json)
ℹ AI provider: claude-code
👽 Thinking...

  ## Security Posture Summary for us-east-2

  ### ✅ Enabled Security Services (2/6)

   GuardDuty - Fully operational

    • Status: ENABLED
    • Finding frequency: Every 6 hours
    • Active data sources: CloudTrail, DNS Logs, VPC Flow Logs,
      S3 Logs, EKS Audit Logs, RDS Login Events
    • Current findings: None (clean)

   Inspector - Partially enabled

    • Status: ENABLED but no scan types active

  ### ❌ Disabled Security Services (4/6)

    1. IAM Access Analyzer - Not configured
    2. Security Hub - Not enabled
    3. Trusted Advisor - Error checking status
    4. Macie - Not enabled

  ### Key Recommendations

   High Priority:
    1. Enable Security Hub for centralized findings aggregation
    2. Enable IAM Access Analyzer
    3. Enable at least one Inspector scan type

   Your security posture is moderate — you have basic threat detection
   enabled but are missing several important security services.

Codex CLI — EC2 Billing​

$ atmos ai ask "What did we spend on EC2 last month in each region?"

ℹ MCP servers configured: 8 (in ~/.codex/config.toml)
ℹ AI provider: codex-cli
👽 Thinking...

   For last month, I used the previous calendar month:
   March 1, 2026 through April 1, 2026.

   EC2 spend by region:

    • us-east-2: $88.10

   Cost Explorer returned only us-east-2 for Amazon Elastic Compute
   Cloud - Compute, so that appears to be the only region with EC2
   spend in that period. AWS also marked the result as Estimated,
   which is normal on April 1, 2026 while billing finalizes.

Both providers automatically selected the right MCP server (aws-security and aws-billing) and returned answers from real AWS data — no manual server selection needed.

Configuration​

You can mix CLI and API providers in the same config and switch between them:

ai:
  default_provider: "claude-code"
  providers:
    claude-code:
      max_turns: 10
    codex-cli:
      full_auto: true
    anthropic:
      model: "claude-sonnet-4-6"
      api_key: !env "ANTHROPIC_API_KEY"

# Uses claude-code (default)
atmos ai ask "What stacks do we have?"

# Override to codex-cli
atmos ai ask --provider codex-cli "What did we spend on EC2?"

# Override to API provider
atmos ai ask --provider anthropic "Describe the vpc component"

Try It​

Learn More​

• AI Documentation
• AI Providers Configuration
• MCP Configuration

Why This Matters​

The MCP ecosystem has hundreds of servers — 20+ from AWS for pricing, security, documentation, and API access; GCP and Azure servers for their respective clouds; plus community servers for databases, monitoring, CI/CD, and custom internal APIs.

Instead of waiting for each cloud integration to be built into Atmos, you can now install any stdio-based MCP server and use it from the Atmos CLI. One atmos.yaml section, zero glue code. Any MCP server that accepts command, args, and env works — AWS, GCP, Azure, or your own custom server.

Quick Start​

Add servers to your atmos.yaml:

mcp:
  servers:
    # Cost Analysis & FinOps
    aws-billing:
      command: uvx
      args: ["awslabs.billing-cost-management-mcp-server@latest"]
      env: { AWS_REGION: "us-east-1" }
      description: "AWS Billing — billing summaries and payment history"
      identity: "readonly"   # Atmos Auth identity (from the auth section)
    aws-pricing:
      command: uvx
      args: ["awslabs.aws-pricing-mcp-server@latest"]
      env: { AWS_REGION: "us-east-1" }
      description: "AWS Pricing — real-time pricing and cost analysis"
      identity: "readonly"   # Atmos Auth identity (from the auth section)

    # Security & Compliance
    aws-security:
      command: uvx
      args: ["awslabs.well-architected-security-mcp-server@latest"]
      env: { AWS_REGION: "us-east-1" }
      description: "AWS Security — Well-Architected security posture assessment"
      identity: "readonly"   # Atmos Auth identity (from the auth section)
    aws-iam:
      command: uvx
      args: ["awslabs.iam-mcp-server@latest"]
      env: { AWS_REGION: "us-east-1" }
      description: "AWS IAM — role/policy analysis and access patterns"
      identity: "readonly"   # Atmos Auth identity (from the auth section)
    aws-cloudtrail:
      command: uvx
      args: ["awslabs.cloudtrail-mcp-server@latest"]
      env: { AWS_REGION: "us-east-1" }
      description: "AWS CloudTrail — event history and API call auditing"
      identity: "readonly"   # Atmos Auth identity (from the auth section)

    # Documentation (no credentials needed)
    aws-docs:
      command: uvx
      args: ["awslabs.aws-documentation-mcp-server@latest"]
      description: "AWS Documentation — search and fetch AWS docs"

Then use them:

# Check what you've configured
atmos mcp list

# Verify a server works
atmos mcp test aws-docs

# See what tools a server exposes
atmos mcp tools aws-pricing

# Cost analysis (uses aws-pricing)
atmos ai ask "What's the on-demand price for m7i.xlarge in us-east-1?"

# Spend breakdown (uses aws-billing)
atmos ai ask "What did we spend on EC2 last month?"

# Billing history (uses aws-billing)
atmos ai ask "Show our billing summary for the past 3 months"

# Security posture (uses aws-security)
atmos ai ask "Is GuardDuty enabled in all regions?"

# IAM analysis (uses aws-iam)
atmos ai ask "List all IAM roles with admin access"

# Audit trail (uses aws-cloudtrail)
atmos ai ask "Show recent API calls from the root account"

# Documentation (uses aws-docs, no credentials needed)
atmos ai ask "How do I configure S3 bucket lifecycle rules?"

Smart Server Routing​

When multiple MCP servers are configured, Atmos automatically selects only the servers relevant to your question using a lightweight routing call to your configured AI provider. This keeps tool payloads small and responses fast, even with dozens of servers configured:

$ atmos ai ask "List all IAM roles with admin access"
ℹ MCP routing selected 1 of 8 servers: aws-iam
ℹ MCP server "aws-iam" started (29 tools)
ℹ Registered 29 tools from 1 MCP server(s)
ℹ AI tools initialized: 39

Use --mcp to override and specify servers directly:

# Specify one server
atmos ai ask --mcp aws-iam "List all admin roles"

# Comma-separated or repeated flags
atmos ai ask --mcp aws-iam,aws-cloudtrail "Who accessed the admin role?"

# Works with all AI commands
atmos ai chat --mcp aws-billing
atmos ai exec --mcp aws-security,aws-iam "audit our security posture"

Visibility​

Atmos shows which MCP servers are active and which tools the AI uses:

ℹ MCP routing selected 2 of 8 servers: aws-docs, aws-pricing
ℹ MCP server "aws-docs" started (4 tools)
ℹ MCP server "aws-pricing" started (7 tools)
ℹ Registered 11 tools from 2 MCP server(s)
ℹ AI tools initialized: 26 total

After the AI responds, tool executions are listed:

---
## Tool Executions (2)
1. ✅ aws-docs → aws.search_documentation (234ms)
2. ✅ aws-pricing → get_pricing (456ms)

Tool usage is not inferred — the AI provider explicitly declares which tools it wants to call via the API protocol (tool_use stop reason with a tool_calls array). Atmos executes the requested tools, sends results back to the AI for the final answer, and records every call. If no tool executions appear, the AI genuinely chose not to use any tools for that question.

CLI Commands​

atmos mcp list            # List configured external servers
atmos mcp tools <name>    # List tools from a server
atmos mcp test <name>     # Test server connectivity
atmos mcp status          # Show all server statuses
atmos mcp restart <name>  # Restart a server
atmos mcp export # Generate .mcp.json for Claude Code / IDE

Standard Config Format​

The command, args, env fields follow the same format used by Claude Code, Codex CLI, and Gemini CLI. Atmos adds description, identity, and timeout as extensions:

mcp:
  servers:
    my-server:
      command: "uvx"                          # Standard
      args: ["package@latest"]                # Standard
      env:                                    # Standard
        AWS_REGION: "us-east-1"
      description: "What this server does"    # Atmos extension
      identity: "my-identity"                 # Atmos Auth identity (from the auth section)
      timeout: "30s"                          # Connection timeout

Atmos Auth Integration​

Use Atmos Auth to inject credentials automatically — no manual AWS_PROFILE setup:

mcp:
  servers:
    aws-security:
      command: uvx
      args: ["awslabs.well-architected-security-mcp-server@latest"]
      identity: "security-audit"   # Atmos Auth identity (from the auth section)

Atmos authenticates through the identity chain, writes isolated credential files, and sets AWS_SHARED_CREDENTIALS_FILE + AWS_PROFILE on the subprocess.

Toolchain Integration​

Map uv to the aqua registry and install via the Atmos Toolchain:

toolchain:
  aliases:
    uv: astral-sh/uv

atmos toolchain install astral-sh/uv@0.7.12

IDE Integration​

Use the same servers from Claude Code, Cursor, or any MCP-compatible IDE:

# Generate .mcp.json from your atmos.yaml config
atmos mcp export

Servers with identity are automatically wrapped with atmos auth exec for credential injection. The generated .mcp.json works with Claude Code out of the box.

Atmos YAML Functions​

Atmos YAML functions work in env values:

mcp:
  servers:
    my-server:
      command: uvx
      args: ["my-server@latest"]
      env:
        AWS_REGION: !env AWS_DEFAULT_REGION    # Read OS env var
        API_KEY: !exec "vault kv get -field=key secret/mcp"  # Run command
        PROJECT_ROOT: !repo-root               # Git root path

See It in Action​

All outputs below are from real AWS accounts. Account IDs, resource identifiers, and internal names have been redacted. Cost figures represent an example of real-world spending.

List configured servers:

$ atmos mcp list
       NAME         STATUS                           DESCRIPTION
─────────────────────────────────────────────────────────────────────────────────────────
 aws-api            stopped  AWS API — direct AWS CLI access with security controls
 aws-billing        stopped  AWS Billing — billing summaries and payment history
 aws-cloudtrail     stopped  AWS CloudTrail — event history and API call auditing
 aws-docs           stopped  AWS Documentation — search and fetch AWS docs
 aws-iam            stopped  AWS IAM — role/policy analysis and access patterns
 aws-knowledge      stopped  AWS Knowledge — managed AWS knowledge base (remote)
 aws-pricing        stopped  AWS Pricing — real-time pricing and cost analysis
 aws-security       stopped  AWS Security — Well-Architected security posture assessment

Explore tools from a security server:

$ atmos mcp tools aws-security
           TOOL                                                         DESCRIPTION
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 CheckSecurityServices     Verify if selected AWS security services are enabled in the specified region and account.
 GetSecurityFindings       Retrieve security findings from AWS security services.
 GetStoredSecurityContext  Retrieve security services data that was stored in context from a previous CheckSecurityServices call.
 CheckStorageEncryption    Check if AWS storage resources have encryption enabled.
 ListServicesInRegion      List all AWS services being used in a specific region.
 CheckNetworkSecurity      Check if AWS network resources are configured for secure data-in-transit.

Test server connectivity:

$ atmos mcp test aws-docs
✓ Server started successfully
✓ Initialization handshake complete
✓ 4 tools available
✓ Server responds to ping

Ask AI with MCP tools:

$ atmos ai ask "How do I configure S3 bucket lifecycle rules?"

ℹ MCP routing selected 1 of 8 servers: aws-knowledge
ℹ MCP server "aws-knowledge" started (6 tools)
ℹ Registered 6 tools from 1 MCP server(s)
ℹ AI tools initialized: 16
👽 Thinking...

   Configuring S3 Bucket Lifecycle Rules

   S3 lifecycle rules automate object management by transitioning objects between
   storage classes, archiving, or expiring them. Here's a comprehensive guide:

  --------

  ## 📋 Lifecycle Rule Structure

   Each rule contains 3 key components:

   Component │ Description
  ───────────┼────────────────────────────────────────────────────────
   Metadata  │ Rule ID and Status (Enabled/Disabled)
   Filter    │ Which objects the rule applies to (prefix, tags, size)
   Actions   │ What to do (transition, expire, delete)

  │  A bucket can have up to 1,000 rules per lifecycle configuration.

  --------

  ## 🔧 Available Actions

   Action                           │ Description
  ──────────────────────────────────┼────────────────────────────────────────────────────────
    Transition                      │ Move objects to a different storage class after N days
    Expiration                      │ Permanently delete current object versions
    NoncurrentVersionTransition     │ Transition old versions in versioned buckets
    NoncurrentVersionExpiration     │ Delete noncurrent versions in versioned buckets
    AbortIncompleteMultipartUpload  │ Cancel incomplete uploads after N days
    ExpiredObjectDeleteMarker       │ Remove expired delete markers

  ---

  ## Tool Executions (1)

  1. ✅ aws-knowledge → aws.search_documentation (2874ms)

Ask AI about billing with MCP tools:

$ atmos ai ask "Show our billing summary for the past 2 months"
ℹ MCP routing selected 1 of 8 servers: aws-billing
ℹ MCP server "aws-billing" started (25 tools)
ℹ Registered 25 tools from 1 MCP server(s)
ℹ AI tools initialized: 35
👽 Thinking...

   I'll retrieve your billing summary for the past 2 months right away!

   Here's your billing summary for the past 2 months (February–March 2026):

  --------

  ## 📊 AWS Billing Summary — February & March 2026

  ### 💰 Monthly Totals

   Service                                  │ Feb 2026 │ Mar 2026 │ Change
  ──────────────────────────────────────────┼──────────┼───────────┼──────────
   Amazon Virtual Private Cloud             │ $309.53  │ $261.17   │ ▼ $48.36
   Amazon Elastic Container Registry Public │ $103.63  │ $103.66   │ ▲ $0.03
   EC2 - Other                              │ $88.12   │ $123.39   │ ▲ $35.27
   AWS Key Management Service               │ $50.94   │ $47.98    │ ▼ $2.96
   Amazon Redshift                          │ $50.87   │ $0.30     │ ▼ $50.57
   Tax                                      │ $47.80   │ $40.98    │ ▼ $6.82
   Amazon Relational Database Service       │ $43.99   │ $0.11     │ ▼ $43.88
   AWS App Runner                           │ $28.42   │ $27.55    │ ▼ $0.87
   AWS WAF                                  │ $18.00   │ $18.00    │ —
   Amazon EC2 Compute                       │ $5.03    │ $15.30    │ ▲ $10.27
   AmazonCloudWatch                         │ $10.08   │ $10.45    │ ▲ $0.37
   Amazon Simple Storage Service            │ $10.08   │ $9.35     │ ▼ $0.73
   Amazon Route 53                          │ $5.61    │ $5.68     │ ▲ $0.07
   Amazon Elastic File System               │ $3.65    │ —         │ ▼ $3.65
   Amazon EC2 Container Registry (ECR)      │ $2.69    │ $2.75     │ ▲ $0.06
   Amazon EKS                               │ —        │ $1.86     │ ▲ $1.86
   Amazon Registrar                         │ —        │ $14.00    │ ▲ $14.00
   AWS Cost Explorer                        │ $2.07    │ $1.91     │ ▼ $0.16
   Other services                           │ ~$1.65   │ ~$1.41    │ ▼ $0.24

  --------

  ### 📈 Grand Totals

   Month      │ Total Cost
  ────────────┼──────────────────
   Feb 2026   │ ~$782.16
   Mar 2026   │ ~$745.26
   Difference │ ▼ $36.90 (-4.7%)

  --------

  ### 🔍 Key Observations

    1. Amazon VPC is the largest cost at ~$261–$310/month (NAT Gateway data
       transfer is typically the main driver). Costs dropped notably in March.
    2. Redshift & RDS dropped sharply in March ($50.87 → $0.30 and
       $43.99 → $0.11), suggesting those resources were stopped or deleted.
    3. EC2 - Other increased by $35 in March — worth investigating if this
       correlates with EBS, data transfer, or Elastic IP costs.
    4. Amazon EC2 Compute tripled in March ($5.03 → $15.30), possibly linked
       to the appearance of EKS ($1.86), indicating new compute workloads.
    5. Amazon Registrar appeared as a new $14 charge in March (domain renewal).

  │  ⚠️ Note: Credits and refunds are excluded from these figures.

  --------

  ## Tool Executions (1)

  1. ✅ aws-billing → cost-explorer (381ms)

Check security posture with MCP tools:

$ atmos ai ask "Is GuardDuty enabled in all regions?"
ℹ MCP routing selected 2 of 8 servers: aws-api, aws-security
ℹ MCP server "aws-api" started (2 tools)
ℹ MCP server "aws-security" started (6 tools)
ℹ Registered 8 tools from 2 MCP server(s)
ℹ AI tools initialized: 18
👽 Thinking...

  ## ❌ GuardDuty is NOT Enabled in All Regions

   GuardDuty is only enabled in 1 out of 34 regions checked.

  ### ✅ Enabled (1 region)

   Region    │ Detector ID
  ───────────┼────────────────────────────────────
   us-east-2 │  <detector-id-redacted>

  ### ❌ Not Enabled (33 regions)

   Region         │ Region         │ Region
  ────────────────┼────────────────┼────────────────
   ap-south-1     │ ap-south-2     │ ap-southeast-1
   ap-southeast-2 │ ap-southeast-3 │ ap-southeast-4
   ap-northeast-1 │ ap-northeast-2 │ ap-northeast-3
   ap-east-1      │ ca-central-1   │ ca-west-1
   eu-central-1   │ eu-central-2   │ eu-north-1
   eu-south-1     │ eu-south-2     │ eu-west-1
   eu-west-2      │ eu-west-3      │ me-central-1
   me-south-1     │ il-central-1   │ af-south-1
   sa-east-1      │ us-east-1      │ us-west-1
   us-west-2      │ mx-central-1   │ ...

  --------

  ### 🔒 Recommendations

    1. Enable GuardDuty in all active regions — even regions where you don't
       actively deploy can be targeted by attackers.
    2. Use a GuardDuty delegated administrator (via AWS Organizations) to
       centrally enable and manage across all accounts and regions.
    3. Consider AWS Security Hub to aggregate findings from all regions.
    4. Prioritize us-east-1, us-west-2, eu-west-1 immediately.

  --------

  ## Tool Executions (4)

  1. ✅ aws-api → call_aws (400ms)
  2. ✅ aws-api → call_aws (14ms)
  3. ✅ aws-api → call_aws (7ms)
  4. ✅ aws-api → call_aws (9450ms)

Audit IAM roles with smart routing:

$ atmos ai ask "List all IAM roles with admin access"
ℹ MCP routing selected 1 of 8 servers: aws-iam
ℹ MCP server "aws-iam" started (29 tools)
ℹ Registered 29 tools from 1 MCP server(s)
ℹ AI tools initialized: 39
👽 Thinking...

   I'll help you find all IAM roles with admin access. Let me fetch the
   list of IAM roles and policies simultaneously.

  --------

  ## 🔐 IAM Roles with Admin Access

  ### 1. ✅ Direct AdministratorAccess Policy (4 attachments)

   Role Name                                        │ Description                                    │ Trust Principal
  ──────────────────────────────────────────────────┼────────────────────────────────────────────────┼───────────────────────────
    AWSReservedSSO_AdministratorAccess_...          │ Allow Full Administrator access to the account │ AWS SSO (SAML Federation)
    AWSReservedSSO_RootAccess_...                   │ Centralized root access to member accounts     │ AWS SSO (SAML Federation)
    AWSReservedSSO_TerraformApplyAccess_...         │ Full Terraform state and account access        │ AWS SSO (SAML Federation)
    AWSReservedSSO_TerraformApplyAccess-Core_...    │ Full Terraform access (core backend)           │ AWS SSO (SAML Federation)

  --------

  ## 📋 Summary

   Category                                  │ Count
  ───────────────────────────────────────────┼──────────
   Full Admin (AdministratorAccess policy)   │ 4 roles
   Broad Terraform/State access (elevated)   │ 4 roles
   AWS Service-Linked Roles (scoped)         │ 13 roles

  --------

  ### 🛡️ Security Recommendations

    1. Review SSO assignments for AdministratorAccess and RootAccess roles.
    2. Audit TerraformApplyAccess roles — ensure MFA/session policies are enforced.
    3. Monitor tfstate roles — cross-account trust across 14 accounts.
    4. Enable CloudTrail for AssumeRole calls on high-privilege roles.

  --------

  ## Tool Executions (2)

  1. ✅ aws-iam → list_roles (314ms)
  2. ✅ aws-iam → list_policies (174ms)

Try It​

Learn More​

• MCP Configuration — Full configuration reference
• MCP Commands — CLI command reference
• AWS MCP Servers — All available AWS servers
• Atmos AI — AI features overview

What's New​

Two new identity kinds make it possible to run Atmos natively in environments where credentials are already available:

• ambient — A cloud-agnostic passthrough that preserves all environment variables as-is. No credential clearing, no IMDS disabling, no file overrides. Use this when you just want Atmos to leave the environment alone.

• aws/ambient — An AWS-specific identity that resolves credentials through the AWS SDK's default credential provider chain. This supports environment variables, shared config files, IRSA web identity tokens, EC2 instance metadata (IMDS), and ECS container credentials. Unlike ambient, it returns real AWS credentials that can be used by chained identities like aws/assume-role.

Quick Start​

EKS Pod with IRSA​

# atmos.yaml
auth:
  identities:
    eks-deployer:
      kind: aws/ambient
      principal:
        region: us-east-1

That's it. The pod's IRSA-injected AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN environment variables are preserved and used by the AWS SDK when Terraform runs.

EC2 Instance Profile​

# atmos.yaml
auth:
  identities:
    instance-creds:
      kind: aws/ambient

The EC2 instance metadata service (IMDS) provides credentials automatically. No region needed if it's set elsewhere.

Simple Passthrough​

# atmos.yaml
auth:
  identities:
    passthrough:
      kind: ambient

Use this when credentials are pre-configured in the environment and you just want Atmos to pass them through without any modification.

Why This Matters​

Previously, Atmos auth explicitly disabled IMDS and cleared IRSA environment variables to prevent accidental credential leakage. This was the right default for developer workstations and interactive SSO flows, but it made it impossible to use infrastructure-provided credentials in:

• EKS pods using IAM Roles for Service Accounts (IRSA)
• EC2 instances with IAM instance profiles
• ECS tasks with task roles
• CI runners with pre-configured AWS credentials

Teams in these environments had to either bypass Atmos auth entirely (losing identity management, integrations, and audit trail) or maintain parallel credential management.

Chaining with Assume Role​

A common pattern in multi-account environments: use the pod's IRSA credentials to assume a role in another account.

# atmos.yaml
auth:
  identities:
    # Base: use the pod's IRSA credentials
    pod-base:
      kind: aws/ambient
      principal:
        region: us-east-1

    # Chain: assume a cross-account role using IRSA as the base
    cross-account-deployer:
      kind: aws/assume-role
      via:
        identity: pod-base
      principal:
        assume_role: "arn:aws:iam::999999999999:role/TerraformDeployRole"

The aws/ambient identity resolves the IRSA credentials, then aws/assume-role uses them to call sts:AssumeRole into the target account.

How It Works​

Every other AWS identity kind in Atmos calls a shared PrepareEnvironment() helper that:

1. Clears credential env vars (AWS_ACCESS_KEY_ID, AWS_WEB_IDENTITY_TOKEN_FILE, etc.)
2. Sets AWS_EC2_METADATA_DISABLED=true
3. Points AWS_SHARED_CREDENTIALS_FILE and AWS_PROFILE to Atmos-managed files

The aws/ambient identity skips all of this. It creates a copy of the environment and returns it with only an optional region override. This allows the AWS SDK's full default credential chain to work naturally.

The ambient identity is even simpler — it returns the environment completely unchanged.

When to Use Each​

Get Started​

• Authentication Configuration — Full auth documentation with ambient examples
• EKS Profile Example — Ready-to-use EKS/IRSA configuration

What Changed​

When running atmos describe affected --upload or atmos list instances --upload, the CLI now checks the serialized payload size before sending. If the payload exceeds the configurable threshold (default 4MB), Atmos splits the data into multiple smaller requests, each tagged with batch metadata (batch_id, batch_index, batch_total) for server-side reassembly.

Key Improvements​

• Automatic chunking - Payloads are split transparently when they exceed the size threshold
• Compact JSON - Upload payloads now use compact JSON serialization, reducing size by ~30%
• Configurable threshold - The max_payload_bytes setting in atmos.yaml lets you tune the chunk size
• Backward compatible - Small payloads send exactly as before; old CLI versions continue to work with updated servers

Why This Matters​

Organizations with large infrastructure footprints (hundreds of stacks and components) were hitting Vercel's serverless function body size limit (~4.5MB) when uploading stack data to Atmos Pro. The existing StripAffectedForUpload optimization reduces payloads by 70-75%, but that was not enough for the largest repositories.

With chunked uploads, there is no practical upper limit on the number of stacks or instances that can be uploaded.

How to Use It​

Chunked uploads work automatically with no configuration required. To customize the chunk size threshold, add max_payload_bytes to the pro section of your atmos.yaml:

settings:
  pro:
    max_payload_bytes: 4194304  # 4MB (default)

Set a lower value if you're behind a reverse proxy with a smaller body size limit, or a higher value if your server supports larger payloads.

Get Involved​

• Report issues at github.com/cloudposse/atmos/issues
• Join the discussion in GitHub Discussions

What Changed​

We introduced the --base flag as a unified replacement for --ref and --sha, and added automatic base resolution when running in CI with ci.enabled: true.

Before​

- name: Describe affected
  run: |
    atmos describe affected \
      --ref ${{ github.event.pull_request.head.sha }} \
      --sha ${{ github.event.action == 'closed' && steps.get_parent.outputs.parent_commit || github.event.pull_request.base.sha }}

After​

- name: Describe affected
  run: atmos describe affected

That's it. No flags needed. Atmos reads GitHub Actions environment variables and event payloads to determine the correct base commit for each event type.

How It Works​

When ci.enabled is true in your atmos.yaml and no explicit --base flag is provided, each CI provider resolves the base commit automatically:

The --base Flag​

The new --base flag replaces both --ref and --sha with a single, intuitive flag that accepts either format:

atmos describe affected --base main
atmos describe affected --base refs/tags/v1.16.0
atmos describe affected --base 3a5eafeab90426bd82bf5899896b28cc0bab3073

The old --ref and --sha flags still work but are now deprecated.

Provider-Agnostic Architecture​

Base resolution is part of the CI provider interface — each provider implements its own ResolveBase() method. GitHub Actions is the first implementation, with the architecture ready for GitLab CI, Jenkins, and other providers.

Get Involved​

Try it out in your GitHub Actions workflows and let us know how it works. Open an issue at github.com/cloudposse/atmos with any feedback.

What Are Gists?​

Gists are shared as-is by community contributors. Unlike maintained examples, gists may need adaptation for your version of Atmos. They serve as inspiration and starting points for building your own workflows.

First Gist: FinOps with AWS MCP Servers​

Our inaugural gist is a masterclass in combining Custom Commands, Auth, and Toolchain to give AI assistants direct access to AWS cost data.

Ask Claude questions like "What did we spend on EC2 last month?" and get real answers from your actual AWS account — all authenticated automatically through Atmos.

# Install all AWS MCP server packages
atmos mcp aws install all

# Start a cost server with automatic AWS auth
atmos mcp aws start cost-explorer

# Test that auth is working
atmos mcp aws test all

The gist configures 21 AWS MCP servers including Billing, Cost Explorer, Pricing, CloudWatch, IAM, and more — all using a single authentication pattern powered by atmos auth exec.

Browse the gist

Contributing a Gist​

Have a creative Atmos recipe? We welcome contributions.

1. Create a directory in gists/ with your config files and a comprehensive README
2. Submit a pull request
3. Your gist will automatically appear on the Gists page

Get Involved​

• Browse the Gists collection
• Join us on Slack
• Attend Office Hours

Live Infrastructure Status​

Atmos Pro gives teams a real-time view of every infrastructure component across all environments. With this release, the status pipeline gets significantly faster: the CLI reports results to Atmos Pro immediately after each terraform operation completes.

When you run atmos terraform plan or atmos terraform deploy with --upload-status, the CLI sends the raw execution result to Atmos Pro. The dashboard updates within seconds, showing whether each component is in sync, has drift, or encountered an error — across every stack, every environment, at a glance.

How It Works​

The CLI sends the raw command and exit code to Atmos Pro, which interprets the result server-side. This means Atmos Pro can refine how it classifies status without requiring a CLI update. The CLI stays simple — it just reports what happened.

# Plan with status reporting
atmos terraform plan mycomponent -s prod-use1 --upload-status

# Apply with status reporting
atmos terraform deploy mycomponent -s prod-use1 --upload-status

In CI workflows, add --upload-status to your plan and apply steps. Combined with the new CI exit code mapping, your workflows stay green while Atmos Pro captures the full picture:

# atmos.yaml
ci:
  enabled: true

components:
  terraform:
    ci:
      exit_codes:
        0: true    # no changes → CI success
        1: false   # error → CI failure
        2: true    # changes detected → CI success

Why This Matters​

Infrastructure teams managing hundreds of components need to know the state of their deployments at all times. Before this change, status updates depended on webhook processing and background reconciliation — introducing delays and gaps. Now the CLI closes that loop directly:

• Instant feedback — dashboard updates seconds after plan or apply finishes
• Complete coverage — both plan and apply report status, including errors
• Zero configuration drift — Atmos Pro always reflects the latest execution result
• CI-native — works seamlessly in GitHub Actions, GitLab CI, or any CI system

If you're managing infrastructure at scale, Atmos Pro turns your CLI output into a shared, real-time operational view for the entire team.

What Changed​

When you run atmos auth console for different identities, each session now opens in its own isolated Chrome browser context. No more logout conflicts when switching between accounts — whether you're using AWS, Azure, or any other supported provider.

Enable it globally in your atmos.yaml:

auth:
  console:
    isolated: true

Or per-invocation with the --isolated flag:

atmos auth console --identity plat-staging/AdministratorAccess --isolated
atmos auth console --identity cards-staging/AdministratorAccess --isolated

Both sessions run simultaneously in separate browser windows with fully isolated cookies and session state.

Why This Matters​

Teams working across multiple cloud accounts frequently need to have several consoles open at once — comparing configurations, debugging cross-account issues, or monitoring deployments across environments. Cloud providers like AWS and Azure enforce a single session per browser context, forcing users to log out and back in every time they switch accounts.

If you've ever seen this, you know the pain:

Isolated sessions solve this by giving each identity its own Chrome browser profile via --user-data-dir. This works for any provider that atmos auth console supports — AWS, Azure, and others as they're added. Sessions are deterministic per identity, so reopening the same identity reuses its profile (no re-login needed within the session lifetime). Different identities are fully isolated.

Platform Support​

Isolated sessions work on any platform with Chrome or Chromium installed:

• macOS: Uses open -na "Google Chrome" --args --user-data-dir=<dir>
• Linux: Uses google-chrome --user-data-dir=<dir>
• Windows: Uses chrome.exe --user-data-dir=<dir>

If Chrome is not installed, Atmos falls back to the default browser with a helpful warning. The feature degrades gracefully — it never blocks console access.

Get Involved​

Have questions or feedback? Join us on Slack or open an issue on GitHub.

What is processArgsAndFlags?​

processArgsAndFlags is the internal workhorse that parses CLI arguments for every atmos terraform, atmos helmfile, and atmos packer invocation. It extracts structured information from raw argument slices: which component to deploy, which stack, which flags to pass through, and which to consume internally.

Before this refactor, the function contained 25+ repetitive if/else chains like this:

if arg == cfg.TerraformCommandFlag {
    if len(inputArgsAndFlags) <= (i + 1) {
        return info, fmt.Errorf(errFlagFormat, errUtils.ErrInvalidFlag, arg)
    }
    info.TerraformCommand = inputArgsAndFlags[i+1]
} else if strings.HasPrefix(arg+"=", cfg.TerraformCommandFlag) {
    terraformCommandFlagParts := strings.Split(arg, "=")
    if len(terraformCommandFlagParts) != 2 {
        return info, fmt.Errorf(errFlagFormat, errUtils.ErrInvalidFlag, arg)
    }
    info.TerraformCommand = terraformCommandFlagParts[1]
}
// ... repeated 24 more times for other flags

This pattern appeared 26 times — once for each string-valued flag. Adding a new flag required copying and adapting 7–8 lines of boilerplate. Missing a case was easy and hard to detect without coverage.

The Refactor: DRY Table-Driven Design​

1. parseFlagValue — One Helper for All Forms​

We extracted a single helper that handles both --flag value (space-separated) and --flag=value (equals-separated) forms:

func parseFlagValue(flag, arg string, args []string, index int) (string, bool, error) {
    if arg == flag {
        if index+1 >= len(args) {
            return "", false, fmt.Errorf(errFlagFormat, errUtils.ErrInvalidFlag, arg)
        }
        return args[index+1], true, nil
    }
    if strings.HasPrefix(arg, flag+"=") {
        // SplitN(..., 2) keeps any additional "=" in the value intact.
        // e.g., --query=.tags[?env==prod] correctly returns ".tags[?env==prod]"
        parts := strings.SplitN(arg, "=", 2)
        return parts[1], true, nil
    }
    return "", false, nil
}

This fixes two latent bugs in the original code:

1. Prefix collision: the old code used strings.HasPrefix(arg+"=", flag) which produced false positives for flags sharing a common prefix (e.g., --terraform-command-extra matching --terraform-command). The new strings.HasPrefix(arg, flag+"=") is correct and unambiguous.

2. Values containing =: the old code used strings.Split(arg, "=") and rejected anything with more than one = sign. This meant --query=.tags[?env==prod] or --append-user-agent=Key=Value would error. Using strings.SplitN(arg, "=", 2) limits the split to the first =, preserving the rest of the value intact.

2. stringFlagDefs — The Table That Replaces 200+ Lines​

All 26 string-valued flags now live in a single declaration:

var stringFlagDefs = []stringFlagDef{
    {cfg.TerraformCommandFlag, func(info *schema.ArgsAndFlagsInfo, v string) { info.TerraformCommand = v }},
    {cfg.TerraformDirFlag,     func(info *schema.ArgsAndFlagsInfo, v string) { info.TerraformDir = v }},
    // ... 24 more entries
    // --planfile sets two fields:
    {cfg.PlanFileFlag, func(info *schema.ArgsAndFlagsInfo, v string) { info.PlanFile = v; info.UseTerraformPlan = true }},
}

Adding a new CLI flag is now a single line. The loop in processArgsAndFlags becomes:

for _, def := range stringFlagDefs {
    val, found, err := parseFlagValue(def.flag, arg, inputArgsAndFlags, i)
    if err != nil {
        return info, err
    }
    if found {
        def.setFunc(&info, val)
        break
    }
}

3. Specialized Helpers for Complex Flags​

Two flags have non-standard semantics and get their own focused helpers:

parseIdentityFlag handles --identity's optional-value behavior:

• --identity → __SELECT__ (prompts for interactive selection)
• --identity value → uses value
• --identity= → __SELECT__ (empty value triggers selection)
• --identity=value → uses value

parseFromPlanFlag handles --from-plan's optional path:

• --from-plan → enables plan mode, no specific file
• --from-plan path → enables plan mode, uses path
• --from-plan=path → enables plan mode, uses path

4. Boolean Flags Consolidated​

Five separate if statements became one switch:

switch arg {
case cfg.DryRunFlag:    info.DryRun = true
case cfg.SkipInitFlag:  info.SkipInit = true
case cfg.HelpFlag1, cfg.HelpFlag2: info.NeedHelp = true
case cfg.AffectedFlag:  info.Affected = true
case cfg.AllFlag:       info.All = true
}

5. Boolean Flag Stripping Bug Fixed​

This was the most insidious bug: every entry in commonFlags — including purely boolean flags like --dry-run, --skip-init, --affected, and --all — was unconditionally stripping both the flag at index i and the next argument at index i+1 from the pass-through list. The result:

# --refresh=false was silently dropped before reaching terraform
atmos terraform plan vpc --stack dev --dry-run --refresh=false

# --parallelism=10 was silently dropped
atmos terraform apply vpc --stack prod --affected --parallelism=10

The fix introduces valueTakingCommonFlags — a set built from stringFlagDefs plus explicitly enumerated value-taking entries (--stack, -s, --global-options, --kubeconfig-path, profiler string flags). The stripping loop now only advances to i+1 for flags that actually consume a value:

if f == cfg.FromPlanFlag || f == cfg.IdentityFlag {
    // Optional-value: only strip i+1 if next arg isn't a flag.
    if len(inputArgsAndFlags) > i+1 && !strings.HasPrefix(inputArgsAndFlags[i+1], "-") {
        indexesToRemove = append(indexesToRemove, i+1)
    }
} else if valueTakingCommonFlags[f] {
    // Value-taking: always strip i+1 (the value was consumed during parsing).
    indexesToRemove = append(indexesToRemove, i+1)
}
// Boolean-only flags: do nothing — i+1 passes through to the underlying tool.

This was a silent data-loss bug: users who combined an Atmos boolean flag with a Terraform flag in the same command line were silently losing their Terraform flag. The bug had existed since the feature was first introduced.

Coverage: From Patchwork to 100%​

All functions in the refactored code now have 100% unit test coverage:

The new test suite adds 12 focused test functions covering:

• Every string flag in both space-separated and equals-separated forms
• All boolean flags (--dry-run, --skip-init, -h, --help, --affected, --all)
• Global options in both --global-options value and --global-options=value forms
• NeedHelp handling with and without a subsequent subcommand
• --from-plan in all four forms (alone, with path, with =path, with =)
• Boolean flags NOT stripping adjacent pass-through flags (regression suite for the stripping bug)
• Error paths: missing values, invalid options
• Flag value stripping from AdditionalArgsAndFlags (both flag and value removed, not just the flag)

Why This Matters​

Every CLI invocation of atmos terraform, atmos helmfile, or atmos packer goes through this code. Confidence in its correctness directly translates to confidence in Atmos as a whole.

With 100% coverage and a table-driven design:

• Adding a new flag is a one-line change
• Bugs are caught immediately by the test suite
• The code is readable — flag definitions are declarations, not imperative code
• Maintenance burden drops — no more copy-paste archaeology

This work is part of Atmos's commitment to pushing test coverage from 74% toward 80%+ while making the codebase increasingly approachable for contributors.

The Problem: A 760-Line Monolith​

ExecuteTerraform was the largest single function in the Atmos codebase. Over time it had grown to handle everything from authentication setup and stack processing to workspace management, provisioner orchestration, plan-file cleanup, and status uploads — all inline, in a single sprawling function.

The cyclomatic complexity score was 160 — more than ten times the project's lint limit of 15. That meant:

• No unit tests — the function required a real atmos.yaml, a real stack, real terraform binaries, and live AWS credentials just to call it.
• Impossible to audit — anyone reviewing a security fix had to trace through hundreds of interleaved branches.
• Fragile changes — adding a new flag required careful reading of the entire function to avoid introducing regressions.

The Approach: Extract, Name, Test​

Rather than rewrite from scratch, we took a disciplined extraction approach:

1. Identify logical boundaries — each block of related code became a candidate for a helper function.
2. Name precisely — function names like setupTerraformAuth, checkComponentRestrictions, and assembleComponentEnvVars communicate intent immediately.
3. Test every helper — because each function now has a clear signature and no side effects beyond its stated purpose, we could write fast, offline unit tests with no infrastructure.
4. Apply DRY — the provisioner-setup logic that was duplicated between the early-init pre-step and the init subcommand path was unified into a single prepareInitExecution helper.

Helper Functions Introduced​

The Result​

After the refactoring:

• ExecuteTerraform complexity: 26 (down from 160)
• buildTerraformCommandArgs complexity: 9 (the most complex helper)
• 100+ new unit tests — all pure in-process, zero infrastructure required
• Zero behavior changes — the entire existing integration test suite passes unchanged

Lessons Learned​

Complexity limits are guardrails, not suggestions. A max-complexity of 15 sounds strict until you see what happens when it is ignored for years.

Test-driven extraction pays off. Writing tests for each extracted helper forced us to think about the contract of each function, which in turn exposed several subtle differences (e.g., the slightly different init-reconfigure logic for the early-init pre-step vs. the init subcommand path).

Naming is architecture. When you can give a 20-line block of code a precise 3-word name, you have found a real abstraction.

Get Involved​

Check out the Atmos GitHub repository and feel free to open issues, contribute code, or share ideas. We welcome contributions from the community!

The Problem with CI Glue Code​

Look at any mature infrastructure repository's CI workflows. You'll find bash scripts parsing terraform output with grep and awk, conditional logic to handle plan files across jobs, and environment variable gymnastics to pass data between steps.

This complexity isn't accidental—it's compensation. When tools aren't designed for CI, teams build layers of glue code to bridge the gap. The cost is real: workflows that work in CI fail locally (and vice versa), debugging requires reproducing the entire CI environment, and tribal knowledge accumulates in workflow files.

The Reproducibility Principle​

Infrastructure tools should follow a simple principle: the same command should produce the same behavior everywhere.

# This should work identically:
atmos terraform plan vpc -s prod    # locally
atmos terraform plan vpc -s prod    # in GitHub Actions
atmos terraform plan vpc -s prod    # in GitLab CI

When a tool is truly CI-native, your workflow files become trivial:

# Before: Complex workflow with hidden logic
- name: Plan
  run: |
    output=$(atmos terraform plan vpc -s prod 2>&1)
    echo "$output"
    # Parse for changes...
    # Upload artifacts...
    # Post PR comment...

# After: CI-native tool
- name: Plan
  run: atmos terraform plan vpc -s prod

What This Enables​

Previously, getting beautiful plan summaries in GitHub Actions required using separate actions like github-action-atmos-terraform-plan. These wrapped the CLI with CI-specific behaviors, creating two codebases that evolved separately.

Now, Atmos handles everything natively. The CLI detects when it's running in CI and automatically generates the same rich output you're used to—resource badges, collapsible diffs, terraform outputs.

What You Get​

• Rich job summaries — resource badges, collapsible diffs, plan/apply templates (written to $GITHUB_STEP_SUMMARY)
• Live status checks — real-time progress ("Plan in progress" → "3 to add, 1 to change, 0 to destroy")
• Output variables — plan/apply results exported to $GITHUB_OUTPUT for downstream jobs
• Planfile storage — store planfiles in S3, GitHub Artifacts, or local filesystem with SHA256 integrity verification
• Custom templates — Go template syntax for full control over summaries and comments
• Auto-detection — CI mode enabled automatically from CI=true or GITHUB_ACTIONS=true
• Same command works locally and in CI
• PR comments (coming soon) — auto-updated plan summaries on pull requests

Quick Start​

Here's a minimal workflow using profiles and auth with OIDC:

name: Terraform Plan

on:
  pull_request:
    branches: [main]

jobs:
  plan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    env:
      ATMOS_PROFILE: ci
      ATMOS_IDENTITY: plat-dev/admin
    steps:
      - uses: actions/checkout@v4
      - uses: cloudposse/github-action-setup-atmos@v2

      - name: Terraform Plan
        run: atmos terraform plan mycomponent -s dev-us-east-1

auth:
  providers:
    github-oidc:
      kind: github/oidc
      region: us-east-2
      spec:
        audience: sts.amazonaws.com

  identities:
    plat-dev/admin:
      kind: aws/assume-role
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::111111111111:role/acme-plat-gbl-dev-terraform

ci:
  # Auto-enabled when CI detected, or set explicitly
  enabled: true

  # Output variables for downstream jobs
  output:
    enabled: true
    variables:
      - has_changes
      - has_additions
      - has_destructions
      - artifact_key
      - plan_summary

  # Job summary with plan/apply results
  summary:
    enabled: true

  # Commit status checks
  checks:
    enabled: true
    context_prefix: "atmos"

  # Template overrides
  templates:
    base_path: ".atmos/ci/templates"
    terraform:
      plan: "plan.md"
      apply: "apply.md"

# To store planfiles across CI pipeline stages, add:
components:
  terraform:
    planfiles:
      # Stores are tried in priority order
      priority:
        - "github"

      # Named stores
      stores:
        github:
          type: github/artifacts
          options:
            retention_days: 7

That's it. Atmos detects GitHub Actions automatically and writes the plan summary to $GITHUB_STEP_SUMMARY.

Example Output​

Changes Found for vpc in dev-us-east-1​

Caution

Terraform will delete resources! This plan contains resource delete operations. Please check the plan result very carefully.

Resources: 3 to add, 0 to change, 1 to destroy.

To reproduce this locally, run:

atmos terraform plan vpc -s dev-us-east-1

---

Create​

+ aws_vpc.main
+ aws_subnet.public[0]
+ aws_subnet.public[1]

Destroy​

- aws_security_group.deprecated

Terraform Plan Summary

# random_id.id2 will be created
  + resource "random_id" "id2" {
      + b64_std     = (known after apply)
      + b64_url     = (known after apply)
      + byte_length = 8
      + dec         = (known after apply)
      + hex         = (known after apply)
      + id          = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

cluster_id = "cluster-754a1c6160064d0b"
lb_id = "load-balancer-763d296bbfc8ccc6"
vpc_id = "vpc-69e5cf6a55e1eb81"

Terraform Outputs

Output	Value
cluster_id	cluster-754a1c6160064d0b
lb_id	load-balancer-763d296bbfc8ccc6
vpc_id	vpc-69e5cf6a55e1eb81

Learn More​

• CI Configuration — complete configuration options and permissions reference
• Native CI Overview — feature overview and architecture
• Planfile Storage — store and verify planfiles across CI pipeline stages

What Changed​

ExecuteDescribeStacks in internal/exec/describe_stacks.go was a 1,160-line monolith that repeated nearly identical component-processing logic four times — once for each component type (Terraform, Helmfile, Packer, Ansible). The duplication made it impossible to unit test individual behaviours and extremely difficult to reason about.

We extracted the shared logic into a new describe_stacks_component_processor.go file containing:

Why This Matters​

Before:

• ExecuteDescribeStacks: cyclomatic complexity 247, cognitive complexity 1252
• 1,160 lines of deeply nested, copy-pasted code
• Practically untestable at a unit level

After:

• ExecuteDescribeStacks orchestrator: cyclomatic complexity 10
• Max complexity across all extracted functions: cyclomatic 20, cognitive 22 (processComponentEntry)
• All pure helper functions covered at ~96% by unit tests (remaining uncovered lines are unreachable defensive type-assertion guards)

How to Use It​

The public API is completely unchanged. ExecuteDescribeStacks accepts the same parameters and returns the same map[string]any. No migration is required.

New Unit Tests​

80+ unit tests now cover every pure helper function at near-100%:

// Example: testing shouldFilterByStack in isolation
func TestShouldFilterByStack(t *testing.T) {
    assert.False(t, shouldFilterByStack("", "stacks/prod.yaml", "prod"))      // no filter
    assert.False(t, shouldFilterByStack("prod", "stacks/prod.yaml", "prod"))  // matches name
    assert.True(t,  shouldFilterByStack("dev", "stacks/prod.yaml", "prod"))   // no match
}

Get Involved​

We're continuing to reduce complexity across the codebase. If you spot a function with high complexity, open an issue or PR. Check the contributing guide to get started.

What Changed​

Every time Atmos resolves a component — merging globals, imports, overrides, base-component settings, environment variables, vars, and backend config — it performs a series of deep merge operations on map[string]any trees. The previous implementation called mergo.Merge on a pre-copied duplicate of every input map, paying two costs per merge step:

1. Full deep-copy of the source map (even keys that would never conflict with the destination).
2. Reflection-based traversal inside mergo to walk the copied map and assign values.

The new implementation replaces this pattern with a single-pass, reflection-free native Go merge:

• The first input is deep-copied once to create the initial accumulator.
• Each subsequent input is merged directly — values are copied into the accumulator only when they are stored as leaves (new keys, scalar overrides, or slice results). Shared intermediate map[string]any containers are recursed into without any allocation.

This reduces N full pre-copies (one per input) down to 1 pre-copy plus O(changed leaves) incremental copies for a typical N-input merge.

Benchmark Results​

# Micro-benchmark (5 inputs, 3 top-level keys)
Before  BenchmarkMerge-4             682 k iter /  5062 ns/op   ← original mergo
After   BenchmarkMerge-4            2514 k iter /  1427 ns/op   ← 3.5× faster

# Production-scale (10 inputs, 25 top-level sections, nested maps + list-of-map-of-list)
After   BenchmarkMerge_ProductionScale-4   27K iter / 44000 ns/op / 10952 B/op / 189 allocs/op

The 3.5× improvement is from the 5-input micro-benchmark. The production-scale benchmark (10 inheritance layers, 25 top-level sections including nested maps, tags, providers, backend, lists, scalars, and deeply nested node_groups with per-group subnet lists — a list-of-map-of-list pattern common in EKS and network stacks) shows ~44 µs per full stack merge on a typical CI/CD server — well under any practical latency budget even for large configurations with many stacks.

Run the production benchmark locally:

go test -run=^$ -bench=BenchmarkMerge_ProductionScale -benchmem ./pkg/merge/...

The improvement scales with the number of inputs and the depth of the configuration tree — exactly the shapes that matter most in production stacks with multiple layers of inheritance.

Semantic Compatibility​

The new implementation preserves the same merge semantics as the mergo-based code for the common cases, including all three list merge strategies (replace, append, merge) and the WithSliceDeepCopy / WithAppendSlice behaviours.

Cross-validation tests (opt-in via go test -tags compare_mergo ./pkg/merge/...) verify the native implementation matches mergo for the core cases. Where behavior intentionally differs, the tests document it as a defined contract (see below).

Edge case: sliceDeepCopy result length​

When sliceDeepCopy is active and the source list is longer than the destination list, the merged result keeps the overlapping merged positions and appends deep-copied source tail elements, so the result length grows to max(len(dst), len(src)). This matches mergo's WithSliceDeepCopy behavior and is cross-validated against mergo in merge_compare_mergo_test.go (run with go test -tags compare_mergo ./pkg/merge/...). See docs/fixes/2026-03-19-deep-merge-native-fixes.md for full edge-case documentation.

Partial mergo replacement​

This change replaces the hot-path deep merge in pkg/merge/merge.go. The mergo library is still used in two lower-traffic call sites:

• pkg/merge/merge_yaml_functions.go — YAML function merge helpers
• pkg/devcontainer/config_loader.go — devcontainer config loading

Migration of these remaining sites is tracked in issue #2242; the dependency will be removed once those two call sites are ported. Until then, a future CVE in mergo could still affect atmos. Follow #2242 for progress.

How to Use It​

No action required — the improvement is automatic from this release onward. If you notice any difference in merge results, please open an issue.

What Changed​

The new dependencies.components section provides a structured way to declare component dependencies:

components:
  terraform:
    app:
      dependencies:
        components:
          - component: vpc
          - component: rds
            stack: "{{ .vars.tenant }}-{{ .vars.environment }}-prod"
          - kind: file
            path: configs/app.json

Key Features​

• Cross-type dependencies: Terraform components can depend on Helmfile components using the kind field
• File/folder watching: Trigger rebuilds when config files change with kind: file or kind: folder
• Template support: Dynamic stack references with Go templates
• Inheritance: Dependencies are replaced during stack inheritance by default, or appended when list_merge_strategy: append is configured

Cross-Type Dependencies​

The kind field allows you to declare dependencies on components of different types:

components:
  terraform:
    app:
      dependencies:
        components:
          - component: vpc                    # terraform (default)
          - component: nginx-ingress
            kind: helmfile                    # helmfile component
            stack: platform-stack

File and Folder Dependencies​

Track external files and folders that affect your component:

components:
  terraform:
    lambda:
      dependencies:
        components:
          - component: vpc
          - kind: file
            path: configs/lambda-settings.json
          - kind: folder
            path: src/lambda/handler

Coming Soon​

In Q1 2026, we're adding automatic dependency detection from YAML functions. Dependencies will be inferred automatically from !terraform.output and !terraform.state usage—no manual configuration needed.

Get Started​

See the Component Dependencies documentation for complete details.

What Changed​

The atmos auth system now supports EKS integrations that automatically provision kubeconfig when you log in:

• aws/eks integration kind - Configure EKS clusters as integrations linked to identities
• atmos aws eks token command - kubectl exec credential plugin for short-lived token generation
• Enhanced atmos aws eks update-kubeconfig - New --integration and --identity flags for Go SDK-based kubeconfig generation
• Automatic cleanup - Kubeconfig entries are removed when you log out

Why This Matters​

Previously, accessing EKS clusters required installing the AWS CLI, running aws eks update-kubeconfig, and managing credentials separately. Now everything is managed through your atmos.yaml configuration:

auth:
  integrations:
    dev/eks:
      kind: aws/eks
      via:
        identity: dev-admin
      spec:
        cluster:
          name: dev-cluster
          region: us-east-2
          alias: dev

A single atmos auth login dev-admin provisions both AWS credentials and kubeconfig entries. kubectl automatically calls atmos aws eks token for fresh tokens when needed.

How to Use It​

1. Add an EKS integration to your atmos.yaml linking a cluster to an identity
2. Run atmos auth login <identity> - kubeconfig is auto-provisioned
3. Use kubectl --context <alias> get pods - tokens are generated automatically

See the EKS Kubeconfig Authentication Tutorial for a complete setup guide.

Get Involved​

Have feedback or questions? Open an issue on GitHub.

The Problem​

When Terraform components use multiple AWS provider aliases for multi-account patterns (e.g., hub-spoke networking), each provider assumes a different IAM role. In CI environments with OIDC authentication, only the primary identity's profile was written to the shared credentials file. The additional provider aliases failed because their AWS profiles didn't exist.

The Solution​

Identities can now be marked as required: true. Before Terraform runs, Atmos automatically authenticates every required identity and writes their profiles to the shared credentials file — no prompting, no selection.

The required field is orthogonal to default:

• default: true — sets the PRIMARY identity (AWS_PROFILE, credential env vars). Only one allowed.
• required: true — auto-authenticate without prompting. Multiple allowed.

Example​

auth:
  identities:
    core-network:
      kind: aws/assume-role
      default: true       # Primary identity
      required: true      # Auto-authenticate
      # ... via, principal, etc. (see full identity config below)
    plat-prod:
      kind: aws/assume-role
      required: true      # Auto-authenticate as secondary
      # ... via, principal, etc.
    plat-staging:
      kind: aws/assume-role
      required: true      # Auto-authenticate as secondary
      # ... via, principal, etc.

This snippet highlights the default and required fields only. Each identity also needs via and principal configuration — see the full identities documentation for complete aws/assume-role examples.

How It Works​

1. Atmos authenticates the default identity as the primary (sets AWS_PROFILE and default credentials).
2. Atmos finds all identities with required: true and authenticates each one.
3. All profiles are written to the shared credentials file, making them available for Terraform provider aliases.
4. Failures for non-primary required identities are non-fatal — Atmos logs a warning and continues.
5. Terraform runs with all profiles available, so multi-account provider aliases resolve correctly.

The --identity CLI flag takes precedence over default for primary selection, but required identities are still authenticated as secondary.

How It Works​

1. Run any Atmos command with --ai
2. The command executes normally — output streams to your terminal in real-time
3. After the command completes, the captured output is sent to the AI provider
4. The AI analysis appears below the command output

Plan Analysis​

$ atmos terraform plan vpc -s ue1-prod --ai

Terraform will perform the following actions:

  # null_resource.vpc will be created
  + resource "null_resource" "vpc" {
      + id       = (known after apply)
      + triggers = {
          + "availability_zones"  = "us-east-1a,us-east-1b,us-east-1c"
          + "environment"         = "production"
          + "nat_gateway_enabled" = "true"
          + "vpc_cidr"            = "10.10.0.0/16"
        }
    }

Plan: 1 to add, 0 to change, 0 to destroy.

✓ AI analysis complete

  ## Terraform Plan Summary:  vpc  in  ue1-prod

  ### Plan Succeeded — 1 Resource to Create

   Metric     │ Value
  ────────────┼───────
   To Add     │ 1
   To Change  │ 0
   To Destroy │ 0

  A  null_resource.vpc  will be created with CIDR  10.10.0.0/16 ,
  3 availability zones, and NAT Gateways enabled.

Error Explanation​

When commands fail, the AI explains the root cause and provides actionable fixes:

$ atmos terraform plan vpc -s ue1-pro --ai

✓ AI analysis complete

  ## Component Not Found Error

   Atmos cannot locate the  vpc  component within the  ue1-pro  stack.

  ## Quick Fix

   Check                           │ Command
  ─────────────────────────────────┼────────────────────────────────────
   Stack name is correct           │  atmos list stacks
   Component is defined in stack   │  atmos list components -s ue1-pro
   No YAML syntax errors           │  atmos validate stacks

Domain-Specific Analysis with --skill​

Pair --ai with --skill for domain-specific expertise. Combine multiple skills with commas or repeated flags:

# Terraform expertise for plan analysis
atmos terraform plan vpc -s ue1-prod --ai --skill atmos-terraform

# Multiple skills (comma-separated)
atmos terraform plan vpc -s ue1-prod --ai --skill atmos-terraform,atmos-stacks

# Multiple skills (repeated flag)
atmos terraform plan vpc -s ue1-prod --ai --skill atmos-terraform --skill atmos-stacks

Enable via Environment Variable​

# Enable for all commands in the session
export ATMOS_AI=true
atmos terraform plan vpc -s ue1-prod

# With skills
ATMOS_AI=true ATMOS_SKILL=atmos-terraform,atmos-stacks atmos terraform plan vpc -s ue1-prod

Works with Everything​

The --ai flag works with any Atmos command:

atmos terraform plan vpc -s ue1-prod --ai
atmos terraform apply vpc -s ue1-prod --ai
atmos describe stacks --ai
atmos validate stacks --ai
atmos list components --ai

Try It​

Learn More​

• AI Configuration — Full configuration reference
• Global Flags — All global flags including --ai and --skill
• AI Skills — Available skills for domain-specific analysis

What Changed​

Previously, if you used Go templates in imported stack manifests (e.g. for dynamic component generation or external systems like Datadog), you had to annotate every import:

import:
  - path: "catalog/datadog-monitors"
    ignore_missing_template_values: true
  - path: "catalog/eks-cluster-tmpl"
    ignore_missing_template_values: true
  - path: "catalog/rds-cluster-tmpl"
    ignore_missing_template_values: true
  # ... repeat for every catalog import

For teams with hundreds of catalog imports, this was a maintenance burden.

The Fix​

Set it once, globally, in atmos.yaml:

templates:
  settings:
    ignore_missing_template_values: true

That's it. All imports across your entire project will now silently skip missing template values instead of failing.

Why This Matters​

Many teams use Go templates in stack manifests to dynamically generate Atmos components (e.g. multi-flavor clusters, per-region replicas), or to pass configuration to external monitoring/observability systems (e.g. Datadog, Grafana). In these cases, not every template variable needs to be provided by Atmos — some are resolved later by the external system.

The ignore_missing_template_values setting instructs Atmos to replace any missing template variable with an empty string rather than returning an error. Setting this globally removes the friction of adding it to every import.

Per-Import Override Still Works​

The global setting is a default. Individual imports can still override it in either direction:

# atmos.yaml
templates:
  settings:
    ignore_missing_template_values: true  # global default

# stacks/prod.yaml
import:
  - path: "catalog/strict-config"
    ignore_missing_template_values: false  # override: fail on missing values for this import

Difference from skip_templates_processing​

Use skip_templates_processing when an import contains Go template syntax meant for another system. Use ignore_missing_template_values when you want Atmos to process your templates but tolerate missing variables.

Get Involved​

We'd love to hear your feedback! Please open an issue if you have questions or suggestions.

Unlike general-purpose AI coding assistants, Atmos AI has deep, native understanding of Atmos stacks, components, inheritance patterns, and infrastructure workflows. It's not just an AI that knows about code—it's an AI that truly understands your infrastructure.

With support for 7 AI providers (including local/offline Ollama), persistent sessions with full conversation memory, tool execution with granular permissions and persistent permission cache, specialized skills for specific tasks, and seamless IDE integration via MCP—Atmos AI brings the productivity patterns of industry-leading AI systems to infrastructure management.

The Problem​

Infrastructure-as-code management is complex. Engineers lose hours searching documentation, debugging YAML configurations, understanding stack inheritance across dozens of files, and onboarding team members. The problem isn't lack of tools—it's the cognitive overhead of managing complex infrastructure.

The Solution: Atmos AI​

Atmos AI solves this through infrastructure-aware intelligence. It's like having an expert Atmos engineer available 24/7, ready to analyze your stacks, validate configurations, answer questions, and help with best practices.

See It in Action​

Ask a question about your infrastructure and Atmos AI automatically inspects your stacks, components, and configuration:

$ atmos ai ask "what stacks and components do we have in the infra?"

👽 Thinking...

  I'll list all the available stacks and components in your infrastructure.

  Based on the infrastructure configuration, here are the stacks and components:

  ## Stacks (4 total)

  1. **ue1-network** - Network stack in us-east-1
  2. **ue1-prod** - Production stack in us-east-1
  3. **uw2-network** - Network stack in us-west-2
  4. **uw2-prod** - Production stack in us-west-2

  ## Components by Stack

  ### ue1-network

  • tgw/attachment - Transit Gateway attachment
  • tgw/hub - Transit Gateway hub
  • vpc - Virtual Private Cloud

  ### ue1-prod

  • tgw/attachment - Transit Gateway attachment
  • vpc - Virtual Private Cloud

  ### uw2-network

  • tgw/attachment - Transit Gateway attachment
  • tgw/cross-region-hub-connector - Cross-region Transit Gateway connector
  • vpc - Virtual Private Cloud

  ### uw2-prod

  • tgw/attachment - Transit Gateway attachment
  • vpc - Virtual Private Cloud

  ## Summary

  Your infrastructure is organized across two AWS regions (us-east-1 and us-west-2),
  with dedicated network and production stacks in each region. The network stacks
  contain Transit Gateway hubs for network connectivity, while the production stacks
  use Transit Gateway attachments to connect to the network infrastructure. All stacks
  include VPC components for network isolation.

What Makes Atmos AI Different?​

• Deep Atmos Understanding — Knows stack structure, inheritance patterns, component relationships, and provides context-aware recommendations.
• Full Conversation Memory — Remembers entire chat history within sessions. Resume conversations days or weeks later with full context.
• Tool Execution — Analyzes infrastructure automatically via read-only operations, real-time YAML/Terraform validation, and a granular permission system.
• Multi-Provider Support — 7 providers including local/offline Ollama. Switch providers mid-conversation with Ctrl+P.
• Persistent Sessions — SQLite-backed storage with named sessions, auto-compact, and cross-platform support.
• Non-Interactive Execution — Run AI prompts programmatically for scripting and CI/CD with structured JSON output.

Key Features​

1. Infrastructure-Aware Intelligence​

Atmos AI has native tools to inspect your infrastructure:

You: What VPC CIDR does production use?

AI: Let me check your configuration...
    [Executes: atmos describe component vpc -s prod-use1-network]

    Your production VPC uses CIDR 10.2.0.0/16 with public subnets,
    private subnets, and NAT Gateways enabled in all AZs.

Available tools include atmos_describe_component, atmos_list_stacks, atmos_validate_stacks, validate_file_lsp, file operations, and web search. See Tool System documentation for the full list.

2. Real-Time Validation with LSP​

Atmos AI integrates with Language Server Protocol to provide IDE-quality validation directly in the chat — catching typos, deprecated properties, and schema violations in YAML, Terraform, and HCL files.

3. Persistent Sessions with Full Memory​

Unlike basic chatbots that forget context, Atmos AI remembers everything within a session. Start an architecture discussion on Monday, resume Tuesday with full context, and reference earlier decisions a week later — all with the same named session.

atmos ai chat --session vpc-migration

Sessions are stored in SQLite with visual session picker (Ctrl+L), provider awareness, and auto-compact for extended conversations. See Sessions documentation.

4. Specialized AI Skills​

Atmos AI provides 21+ specialized skills you can install from the marketplace:

# Install all official skills with one command
atmos ai skill install cloudposse/atmos

Skills include atmos-terraform, atmos-stacks, atmos-validation, atmos-components, atmos-config, and many more — each with tailored prompts and tool access for its domain.

Switch skills with Ctrl+A during conversations! See AI Skills documentation.

5. Multi-Provider Support​

Choose the right AI for your needs: