cloudposse/atmos v1.214.0

on GitHub

what

• Add 3 new CLI AI providers that invoke locally installed AI tools as subprocesses: claude-code, codex-cli, gemini-cli
• MCP pass-through for CLI providers — configured MCP servers are automatically passed to the CLI tool via its native config format
• ATMOS_ env var injection* for Codex CLI MCP servers (they don't inherit parent process env)
• No API keys needed — CLI providers reuse the user's existing subscription (Claude Pro/Max, ChatGPT Plus/Pro, Google account free tier)

Available CLI Providers

MCP Pass-Through

Each provider uses its native config format:

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?"

See It in Action

All outputs below are from a real AWS account.

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
    • 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

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.

Both providers automatically selected the right MCP server and returned answers from real AWS data — no manual server selection needed.

why

Why run Claude Code through Atmos instead of the other way around?

Both directions work — you can start a Claude Code session and call Atmos inside it, or use Atmos to invoke Claude Code. Here's when each approach makes sense:

Starting Claude Code → calling Atmos (via MCP server)

claude
# Then inside Claude Code: @atmos-expert "list all stacks"

How it works: Claude Code connects to the Atmos MCP server (atmos mcp start) and uses Atmos tools directly from the IDE.

Best for:

• Long interactive coding sessions where you need AI + infrastructure context
• IDE-driven workflows (Claude Code in VS Code, Cursor, etc.)
• When you want Claude Code's full toolset (file editing, bash, web search) alongside Atmos tools
• Exploratory work — "help me understand and modify this infrastructure"

Limitations:

• Requires setting up the MCP server in your IDE config (.claude/mcp.json)
• Only has access to native Atmos tools — no external AWS MCP servers (billing, security, IAM) unless you configure them separately in Claude Code's own MCP config
• Auth credentials for AWS MCP servers must be configured manually in the IDE config

Atmos → starting Claude Code (this PR)

atmos ai ask "What did we spend on EC2 last month?"

How it works: Atmos invokes claude -p as a subprocess, passing MCP servers with auth credentials pre-configured.

Best for:

• Quick one-shot queries from the terminal (atmos ai ask)
• When you need external MCP servers (AWS billing, security, IAM, CloudTrail) with automatic auth
• CI-adjacent workflows — scripting AI analysis into your workflow
• Multi-provider switching — same question to Claude Code, Codex, or Gemini
• Teams that manage MCP servers centrally in atmos.yaml — one config, every developer gets the same tools

Key advantage — centralized MCP + auth orchestration:

# atmos.yaml — one config for the whole team
mcp:
  servers:
    aws-billing:
      command: uvx
      args: ["awslabs.billing-cost-management-mcp-server@latest"]
      identity: "readonly"   # Atmos Auth handles SSO → credentials automatically

auth:
  providers:
    aws-sso:
      kind: aws/iam-identity-center
      start_url: "https://your-org.awsapps.com/start"
  identities:
    readonly:
      kind: aws/permission-set
      provider: aws-sso
      principal:
        permission_set: "ReadOnlyAccess"
        account:
          id: "123456789012"

When you run atmos ai ask, Atmos:

1. Authenticates via SSO (once, cached)
2. Generates MCP config with credential injection (atmos auth exec -i readonly --)
3. Injects toolchain PATH so uvx is available
4. Passes everything to Claude Code via --mcp-config
5. Claude Code uses AWS MCP tools with real credentials — zero manual setup

With the "Claude Code first" approach, each developer would need to manually configure AWS credentials, MCP server paths, and toolchain binaries in their personal IDE config.

Summary

They're complementary, not competing. Use Claude Code directly for coding sessions in your IDE. Use atmos ai ask/chat for quick infrastructure queries with centralized MCP + auth. Both can be configured in the same project.

Additional motivation

• Many developers already have Claude Code or Codex installed with active subscriptions ($20-200/mo). CLI providers let them reuse that investment instead of purchasing separate API tokens.
• CLI providers handle their own tool execution loop, which means they can use all their built-in tools (file search, code editing, web browsing) alongside MCP-provided AWS tools.
• This completes the AI provider ecosystem: 7 API providers + 3 CLI providers = 10 total providers.

Key Findings During Implementation

Codex CLI

• -c flag overrides do NOT register MCP servers as tools — must write to ~/.codex/config.toml
• --full-auto only auto-approves file writes, not MCP tool calls — need --dangerously-bypass-approvals-and-sandbox
• JSONL output uses item.type="agent_message" with item.text directly (not documented "message" with nested content[])
• MCP servers don't inherit parent env — ATMOS_* vars must be explicitly injected

Gemini CLI

• MCP is blocked server-side for ALL personal Google accounts (oauth-personal auth) regardless of subscription tier
• This is a Google infrastructure restriction (proxy cloudcode-pa.googleapis.com has MCP feature flag disabled)
• The Atmos implementation is complete — MCP will work when Google enables it for personal accounts
• Switching to API key auth enables MCP but loses the free-tier benefit (equivalent to existing gemini API provider)

New Files

Code

• pkg/ai/agent/claudecode/ — Claude Code CLI provider with MCP pass-through
• pkg/ai/agent/codexcli/ — OpenAI Codex CLI provider with ~/.codex/config.toml backup/restore and ATMOS_* injection
• pkg/ai/agent/geminicli/ — Gemini CLI provider with .gemini/settings.json in cwd
• pkg/mcp/client/mcpconfig.go — Shared MCP config generation (env uppercasing, PATH dedup, toolchain injection)

Documentation

• Blog post: website/blog/2026-04-01-ai-cli-providers.mdx
• Example: examples/ai-claude-code/ — Complete example with AWS MCP servers and automatic auth
• PRD: docs/prd/atmos-ai-local-providers.md (v1.6)
• Website docs updated: ai/ai.mdx, ai/troubleshooting.mdx, cli/configuration/ai/index.mdx, cli/configuration/ai/providers.mdx, cli/configuration/mcp/index.mdx, cli/commands/ai/ask.mdx, cli/commands/ai/exec.mdx, cli/commands/ai/usage.mdx
• Roadmap: 4 shipped milestones added to ai-assistant initiative

Tests

• 40+ unit tests across all three CLI provider packages
• Coverage: claudecode 63%, codexcli 72%, geminicli 66%, mcp/client 83%, base 88%

references

• PRD: docs/prd/atmos-ai-local-providers.md
• Blog: website/blog/2026-04-01-ai-cli-providers.mdx
• Example: examples/ai-claude-code/
• Claude Code CLI Reference
• OpenAI Codex CLI
• Gemini CLI

Summary by CodeRabbit

• New Features

  • Added three CLI AI providers: Claude Code, Codex CLI, and Gemini CLI (use local CLI subscriptions; no API keys)
  • CLI providers support MCP pass-through (Atmos forwards configured MCP servers to the CLI)
  • New per-provider settings: binary, max_turns, max_budget_usd, allowed_tools, full_auto
  • UI now displays the selected AI provider
  • New example project demonstrating Claude Code CLI usage and Terraform VPC example

• Documentation

  • New quick-starts, guides, troubleshooting, and PRD updates distinguishing API vs CLI providers and MCP pass-through workflows

what

• Add auto-detection of the base commit in CI environments when ci.enabled is true, eliminating verbose --ref/--sha flag wiring in GitHub Actions workflows
• Introduce unified --base flag as a single replacement for the confusingly-named --ref and --sha flags (both pointed to the base commit)
• Extend the CI Provider interface with ResolveBase() method for provider-agnostic base resolution
• Implement GitHub Actions base resolution covering all event types: PR open/sync, PR closed/merged, push, force-push, and merge group
• Implement generic provider with ATMOS_CI_BASE_REF env var support for local testing
• Deprecate --ref and --sha as hidden aliases

why

• Users had to write verbose, error-prone shell expressions to wire --ref and --sha in GitHub Actions workflows
• The flag names were confusing — both --ref and --sha referred to the base commit, but their names didn't convey this
• With ci.enabled, Atmos should auto-detect the base commit from CI environment variables, achieving zero-config operation
• Provider-agnostic architecture allows future GitLab CI, Jenkins, etc. implementations without changing the core logic

references

• PRD: docs/prd/native-ci/framework/base-resolution.md
• Blog post: website/blog/2026-03-21-describe-affected-auto-detection.mdx
• Docusaurus docs updated: website/docs/cli/commands/describe/describe-affected.mdx
• Roadmap milestone added to CI/CD Simplification initiative

Summary by CodeRabbit

• New Features

  • Unified --base flag for specifying the comparison base
  • Automatic base commit detection in CI when ci.enabled is true, with GitHub Actions support
  • ATMOS_CI_BASE_REF environment override for local testing

• Deprecated

  • --ref and --sha flags deprecated; use --base instead

• Documentation

  • Updated CLI docs, blog post, examples, and roadmap entry describing flag precedence and CI auto-detection

• Tests

  • Added extensive unit/integration tests covering base resolution and CI scenarios

• Chores

  • CI provider registry reset helper added

what

• Connect Atmos to external MCP servers (AWS, GCP, Azure, custom) and use their tools in atmos ai ask, atmos ai chat, and atmos ai exec
• Add CLI MCP management commands: atmos mcp list, tools, test, status, restart, start, export
• Add smart server routing — automatically selects only the MCP servers relevant to the user's question using a lightweight routing call to the configured AI provider
• Add --mcp flag on all AI commands for manual server selection (supports --mcp aws-iam,aws-billing and --mcp aws-iam --mcp aws-billing), env var ATMOS_AI_MCP
• Add atmos mcp export to emit .mcp.json for Claude Code / Cursor / IDE integration
• Add Atmos Auth integration — identity field on server config for automatic credential injection (references identities from the auth section)
• Add toolchain integration — resolves uvx/npx from .tool-versions before starting servers
• Add BridgedTool pattern to wrap external MCP tools as native Atmos tools.Tool interface
• Add human-readable tool names in output (aws-iam → list_roles instead of aws-iam__list_roles)
• Add tool execution display to atmos ai ask output via MarkdownFormatter
• Add configurable ai.max_tool_iterations (default 25, was hardcoded 10) to support complex multi-tool queries
• Add complete example with 8 pre-configured AWS MCP servers at examples/mcp/
• Add comprehensive documentation: MCP Configuration, MCP Commands, AI Landing Page

why

• Leverage the ecosystem — 100+ MCP servers exist for AWS, GCP, Azure, databases, monitoring, CI/CD. Instead of reimplementing cloud provider functionality, Atmos orchestrates existing MCP servers
• Parity with AI tools — Claude Code, Cursor, Windsurf all manage MCP servers. Atmos should too
• Speed — Installing an AWS MCP server takes seconds. Building equivalent functionality takes weeks
• Composability — Users can mix native Atmos tools (describe stacks, validate) with external tools (AWS billing, security, IAM) in the same AI conversation

references

• PRD: docs/prd/atmos-mcp-integrations.md
• Blog post: website/blog/2026-03-29-mcp-server-integrations.mdx
• Example: examples/mcp/ — complete working example with 8 AWS MCP servers
• AWS MCP Servers — 20+ servers for the AWS ecosystem
• MCP Protocol Specification

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 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 — documentation search (smart routing selects aws-knowledge)

$ 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...

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

Ask AI — billing analysis (smart routing selects aws-billing)

$ 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...

  ## 📊 AWS Billing Summary — February & March 2026

   Service                                  │ Feb 2026 │ Mar 2026 │ Change
  ──────────────────────────────────────────┼──────────┼───────────┼──────────
   Amazon Virtual Private Cloud             │ $309.53  │ $261.17   │ ▼ $48.36
   EC2 - Other                              │ $88.12   │ $123.39   │ ▲ $35.27
   ...

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

Ask AI — security posture across all regions (smart routing selects aws-api + aws-security)

$ 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
   eu-central-1   │ eu-west-1      │ us-east-1
   us-west-2      │ ...            │

  ### 🔒 Recommendations
    1. Enable GuardDuty in all active regions
    2. Use delegated administrator via AWS Organizations
    3. 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)

Ask AI — IAM audit (smart routing selects aws-iam)

$ 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...

  ## 🔐 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)

  ### 🛡️ 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)

Check status of all servers

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

Summary by CodeRabbit

• New Features

  • External MCP server support with new mcp commands: list, tools, test, status, restart, export
  • New --mcp / ATMOS_AI_MCP flag for ai ask/chat/exec to select servers (overrides routing)
  • Smart MCP routing to choose relevant servers per prompt
  • Human-friendly tool names in AI responses
  • Configurable AI request timeouts and max tool‑iteration limits

• Documentation

  • Extensive MCP and AI integration docs, examples, and an AWS MCP example

what

• Added a process-level in-memory credential cache (sync.Map) to authenticateChain() that stores successfully authenticated credentials keyed by realm + chain identity
• When a subsequent authentication request matches the same realm and chain within the same CLI invocation, the cached credentials are returned (after expiration validation) without making additional API calls
• The previous fix (dbcba35) that skips cached target identity credentials in keyring/file storage remains intact - this cache layer sits above it

why

• The previous fix correctly prevented stale cached credentials from being returned by always forcing re-authentication of the target identity (e.g., AssumeRole). However, during atmos describe affected, each !terraform.state YAML function resolution creates a new AuthManager via resolveAuthManagerForNestedComponent, and each one triggers a full AssumeRole API call
• This caused atmos describe affected to degrade from ~2 minutes to ~17 minutes due to N redundant STS AssumeRole calls for N components sharing the same auth chain
• The in-memory cache is inherently safe: unlike keyring/file caches that persist across processes and may contain stale data from different auth mechanisms (e.g., pod credentials vs. role credentials), process-scoped credentials were authenticated during the current invocation and are guaranteed correct
• Cached entries are validated against the existing expiration buffer (minCredentialValidityBuffer = 15m) before reuse, and the cache resets naturally when the process exits

references

• Previous fix: dbcba35#diff-de62c2ba7fdbec5bab3d1554349f5082c4ec6cc1378a3b38d14f8a7efb649b62

Summary by CodeRabbit

• New Features

  • Process-level in-memory credential cache to speed repeated authentications and share valid credentials across instances.
  • Automatic detection and removal of expired/invalid cached credentials with transparent re-authentication.
  • Ability to reset the process credential cache.

• Tests

  • Tests verifying cache hits, isolation by realm/chain, expiration handling, and cache reset behavior.

Fields included in upload (allowlist)

• component — instance identification
• stack — instance identification
• component_type — terraform or helm
• settings.pro — drift detection configuration (enabled flag, detect/remediate workflows)

Fields excluded (never serialized)

• vars — can contain secrets
• env — can contain secrets and credentials
• backend — contains role ARNs and bucket names
• source — not used by Atmos Pro
• metadata — not used by Atmos Pro
• All settings keys except pro — not used by Atmos Pro

Why

• Previously, InstancesUploadRequest used []schema.Instance which included all sections from the stack config
• env and vars can contain secrets that should never leave the CI environment
• Nested YAML maps in the excluded fields produce map[interface{}]interface{} types that encoding/json cannot marshal, causing atmos list instances --upload to fail with json: unsupported type: map[interface {}]interface {}
• Using an allowlist DTO ensures new fields added to schema.Instance are never inadvertently uploaded

Summary by CodeRabbit

Release Notes

• Refactor
  • Optimized instance upload payloads by streamlining the data structure to include only essential configuration fields (component, stack, component type, and settings).
  • Enhanced upload efficiency by automatically filtering and extracting pro-specific settings before transmission.

what

• Move atmos auth ecr-login command to atmos aws ecr login under the AWS namespace
• Create new cmd/aws/ecr/ package with parent ECR command and login subcommand
• Move ECR login tests to new package structure (16 tests, all passing)
• Relocate documentation from auth/ to aws/ command directory
• Update all cross-references in tutorials, blog posts, and internal design docs

why

The auth namespace must remain provider-agnostic per CLI design principles. AWS-specific commands like ECR login belong under the atmos aws namespace hierarchy, following the established pattern with atmos aws eks update-kubeconfig. This ensures the auth namespace is not polluted by provider- or service-specific commands and maintains a clean separation between generic auth operations and cloud-specific integrations.

references

Closes #ATMOS-37

Acceptance criteria from ATMOS-37:

• ✅ No AWS- or ECR-specific commands exist directly under atmos auth
• ✅ Command structure aligns with interface-based design
• ✅ CLI help and docs reflect the updated command hierarchy

Summary by CodeRabbit

• New Features

  • Moved ECR login into the AWS namespace as atmos aws ecr login, added top-level ecr subcommand, introduced a command-local --identity flag, and retained multi-registry --registry support.

• Tests

  • Removed legacy test suite and added a comprehensive test suite validating the new command wiring, flags, argument flows, and auth-manager behavior.

• Documentation

  • Updated CLI docs, tutorials, PRD, and blog examples to reference atmos aws ecr login.

• Chores

  • Added new sentinel errors for clearer ECR login failure and identity-selection reporting.

what

• Skip identity resolution in all four describe commands (describe component, describe stacks, describe affected, describe dependents) when --process-functions=false
• Use cmd.Flags().Changed(IdentityFlagName) instead of identityName != "" so that only an explicit --identity CLI flag bypasses the guard — ATMOS_IDENTITY env vars no longer trigger auth when functions are disabled
• Add 10 regression tests covering: auth skipped when functions disabled, env var doesn't bypass guard, explicit --identity flag forces auth, and unit tests for the Changed vs env var distinction

why

• When all YAML functions are disabled via --process-functions=false, describe commands were still attempting identity resolution (SSO login, credential fetching, etc.)
• YAML functions (!terraform.state, !terraform.output) are the only consumers of auth credentials during describe — no functions means no auth needed
• The original guard treated env vars (ATMOS_IDENTITY) as equivalent to explicit CLI flags, causing auth to run even when the user only wanted raw config inspection
• This caused unnecessary authentication prompts/errors in CI and local development

references

• Affects cmd/describe_component.go, cmd/describe_stacks.go, cmd/describe_affected.go, cmd/describe_dependents.go

Summary by CodeRabbit

• Bug Fixes

  • Describe commands now skip unnecessary authentication resolution unless YAML functions processing is enabled or an identity flag was explicitly provided, avoiding spurious auth errors and improving reliability.

• Tests

  • Added regression tests covering auth-skip behavior across describe commands and verifying explicit identity-flag vs environment-variable semantics.

• Refactor

  • Reworked describe command wiring to improve dependency injection and execution plumbing for component description.

• Wrap all Atmos Pro API errors in the Error Builder pattern with status-specific hints and documentation links
• Add ui.Success/ui.Error messages when --upload completes or fails (previously silent on success, swallowed on failure)
• Consolidate fragmented hints into self-contained statements (each hint gets its own lightbulb icon)
• Remove duplicate quickstart links from 404 hints
• Replace fmt.Errorf error wrapping with errors.Join + buildProAPIError across all Pro API paths (uploads, lock/unlock, OIDC exchange)

why

• Users seeing a 403 from Atmos Pro had no guidance on what to do — the error message was opaque (e.g. API request failed with status 403). The most common cause is per-repo permissions not being configured.
• Each HTTP status now links to the most relevant Atmos Pro doc page:
  • 403 → Permissions + Quickstart
  • 401 → GitHub Workflows + Authentication
  • 404 → Install
  • 5xx → Troubleshooting
• Successful uploads were completely silent — users had no confirmation the upload worked
• Upload failures were silently swallowed (log.Warn only) — now they surface as proper errors with hints

references

• Triggered by user report: 403 on atmos describe affected --upload with no actionable guidance
• Atmos Pro docs: https://atmos-pro.com/docs/learn/permissions

Summary by CodeRabbit

• Bug Fixes

  • API errors now include richer context (HTTP status, operation, trace IDs) and status-specific troubleshooting hints; non-JSON responses include a troubleshooting link. Token exchange and lock/unlock failures surface improved, consistent error information.

• New Features

  • User-facing success and error notifications when uploading affected stacks.

• Tests

  • Added tests validating status-specific hints, non-JSON error handling, and trace ID presence.