why

• Provides convenient browser access to cloud consoles without manually copying credentials
• Eliminates context switching between terminal and browser for console access
• Uses provider-native federation endpoints for secure temporary access
• Extensible interface pattern supports future Azure/GCP implementations

features

• Service Aliases: Use shorthand like s3, ec2, lambda instead of full console URLs
• Autocomplete: Shell completion for destination and identity flags
• Session Control: Configurable duration (up to 12 hours for AWS) with expiration display
• Clean Output: URL only shown on error or with --no-open flag
• Scriptable: --print-only flag for piping URLs to other tools
• Provider-Agnostic: Interface design ready for multi-cloud support

implementation

• Created ConsoleAccessProvider interface in pkg/auth/types/interfaces.go
• Implemented ConsoleURLGenerator for AWS using federation endpoint
• Added ResolveDestination() with case-insensitive alias lookup
• Moved HTTP utilities from pkg/utils to dedicated pkg/http package
• Used existing OpenUrl() function for cross-platform browser opening
• Added comprehensive tests achieving 85.9% coverage

testing

• Unit tests for console URL generation (15 test cases)
• Unit tests for destination alias resolution (100+ aliases tested)
• Mock HTTP client for testing without network calls
• Table-driven tests with edge case coverage

documentation

• CLI reference: website/docs/cli/commands/auth/console.mdx
• Blog post: website/blog/2025-10-20-auth-console-web-access.md
• Proposal document: docs/proposals/auth-web-console.md
• Embedded markdown usage examples

references

• Similar to aws-vault's console login feature
• AWS Federation Endpoint: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-custom-url.html

Summary by CodeRabbit

• New Features

  • Added atmos auth console: opens cloud provider web consoles via temporary sign-in URLs (AWS supported now; Azure/GCP planned).
  • Supports service aliases (s3, ec2, etc.), full destination URLs, session duration (AWS up to 12h), issuer, --print-only, --no-open and identity selection/completion.

• Documentation

  • New CLI docs, usage guide, PRD and blog post with examples and troubleshooting.

• Tests

  • Expanded tests and CI snapshots for the new command and destination resolution.

why

• CI test runs were showing verbose YAML dumps to stderr even when tests passed
• This cluttered test output and made it difficult to identify actual issues
• Debug information is still valuable when tests fail, but shouldn't appear during successful runs
• Go's t.Log() always outputs to stderr, regardless of test success/failure

demo

Finally clean output!

go mod download
Running tests with subprocess coverage collection
ok  	github.com/cloudposse/atmos	7.020s	coverage: 14.8% of statements in ./...
ok  	github.com/cloudposse/atmos/cmd	7.581s	coverage: 20.7% of statements in ./...
ok  	github.com/cloudposse/atmos/cmd/about	0.134s	coverage: 0.1% of statements in ./...
ok  	github.com/cloudposse/atmos/cmd/internal	0.099s	coverage: 0.1% of statements in ./...
?   	github.com/cloudposse/atmos/cmd/markdown	[no test files]
ok  	github.com/cloudposse/atmos/cmd/version	1.802s	coverage: 1.4% of statements in ./...
ok  	github.com/cloudposse/atmos/errors	0.213s	coverage: 0.4% of statements in ./...
ok  	github.com/cloudposse/atmos/internal/aws_utils	0.120s	coverage: 0.1% of statements in ./...
ok  	github.com/cloudposse/atmos/internal/exec	84.175s	coverage: 32.9% of statements in ./...
ok  	github.com/cloudposse/atmos/internal/terraform_backend	32.223s	coverage: 0.9% of statements in ./...
	github.com/cloudposse/atmos/internal/tui/atmos		coverage: 0.0% of statements
	github.com/cloudposse/atmos/internal/tui/components/code_view		coverage: 0.0% of statements
ok  	github.com/cloudposse/atmos/internal/tui/templates	0.125s	coverage: 0.5% of statements in ./...
	github.com/cloudposse/atmos/internal/tui/templates/term		coverage: 0.0% of statements
ok  	github.com/cloudposse/atmos/internal/tui/utils	0.218s	coverage: 0.2% of statements in ./...
	github.com/cloudposse/atmos/internal/tui/workflow		coverage: 0.0% of statements
ok  	github.com/cloudposse/atmos/pkg/atlantis	1.434s	coverage: 10.3% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth	0.141s	coverage: 2.1% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/cloud/aws	0.113s	coverage: 0.8% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/credentials	0.316s	coverage: 0.9% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/factory	0.141s	coverage: 0.2% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/identities/aws	0.139s	coverage: 1.7% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/list	0.138s	coverage: 1.5% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/providers/aws	0.098s	coverage: 1.6% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/providers/github	0.072s	coverage: 0.3% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/providers/mock	0.133s	coverage: 0.1% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/types	0.075s	coverage: 0.2% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/utils	0.099s	coverage: 0.0% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/auth/validation	0.150s	coverage: 0.7% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/aws	0.199s	coverage: 2.4% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/component	0.898s	coverage: 10.1% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/component/mock	0.178s	coverage: 0.4% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/config	3.247s	coverage: 5.7% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/config/homedir	0.073s	coverage: 0.2% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/convert	0.048s	coverage: 0.0% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/datafetcher	0.228s	coverage: 0.2% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/describe	29.214s	coverage: 13.2% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/downloader	1.115s	coverage: 1.6% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/filematch	0.135s	coverage: 0.3% of statements in ./...
	github.com/cloudposse/atmos/pkg/filesystem		coverage: 0.0% of statements
ok  	github.com/cloudposse/atmos/pkg/filetype	0.078s	coverage: 0.4% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/generate	0.685s	coverage: 7.7% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/git	0.164s	coverage: 0.3% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/github	2.462s	coverage: 0.4% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/hooks	0.264s	coverage: 7.5% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/list	2.193s	coverage: 12.0% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/list/errors	0.073s	coverage: 0.1% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/list/flags	0.072s	coverage: 0.1% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/list/format	0.119s	coverage: 0.6% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/list/utils	0.187s	coverage: 0.2% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/logger	0.161s	coverage: 0.3% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/merge	0.227s	coverage: 1.7% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/pager	0.076s	coverage: 0.9% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/perf	1.238s	coverage: 0.5% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/pro	0.177s	coverage: 0.8% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/pro/dtos	0.051s	coverage: 0.0% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/profiler	1.861s	coverage: 0.4% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/provenance	0.130s	coverage: 1.8% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/retry	0.176s	coverage: 0.2% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/schema	0.070s	coverage: 0.3% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/spacelift	0.787s	coverage: 8.4% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/stack	0.346s	coverage: 4.3% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/store	0.139s	coverage: 1.7% of statements in ./...
ok  	github.com/cloudposse/atmos/pkg/telemetry	0.518s	coverage: 2.7% of statements in ./...
	github.com/cloudposse/atmos/pkg/telemetry/mock		cov...

what

• Enhanced version list and show commands with improved UI formatting
• Added borderless table with header separator for version list output
• Implemented markdown rendering for release titles with ANSI color preservation
• Added terminal width detection with minimum width validation
• Styled release assets with muted file sizes and underlined download links
• Added spinner animation during GitHub API calls for better UX
• Implemented platform-specific asset filtering (OS/architecture matching)
• Added debug logging for terminal width detection
• Refactored version commands to self-contained cmd/version package following command registry pattern
• Created GitHubClient interface for improved testability
• Updated environment variable binding to support ATMOS_GITHUB_TOKEN with GITHUB_TOKEN fallback

why

• Improve user experience with cleaner, more readable version output
• Make release information more accessible with markdown-rendered titles
• Ensure proper display across different terminal widths
• Provide visual feedback during network operations
• Follow Atmos architectural patterns with self-contained command packages
• Enable better testing through interface-based design
• Support standard Atmos environment variable conventions

references

• Related to version command improvements
• Follows command registry pattern documented in docs/prd/command-registry-pattern.md

Summary by CodeRabbit

• New Features

  • New version commands: list and show — interactive spinner (TTY) with non‑TTY fallback, text/JSON/YAML outputs, pagination, date filtering, prerelease options, current-version indicators, markdown-rendered titles, platform-aware asset listings and tables.

• Authentication

  • GitHub token handling now prefers ATMOS_GITHUB_TOKEN over GITHUB_TOKEN and is bound earlier during startup.

• Errors

  • New clear sentinels for rate limits, invalid limits/offsets, unsupported formats, narrow terminals, and spinner failures.

• Documentation

  • PRDs, usage guides, and a blog post for the new commands.

• Tests

  • Extensive unit and integration tests for list/show, formatters, GitHub client, and edge cases.

• Chores

  • Increased cache lock retry attempts.

what

• Add new global --chdir / -C flag for changing working directory before command execution
• Add ATMOS_CHDIR environment variable support as alternative to flag
• Implement TestKit pattern following Go 1.15+ testing.TB interface for systematic test isolation
• Fix StringSlice flag corruption using reflection-based cleanup
• Improve error messages for empty or missing config paths
• Create comprehensive test suite with 15+ test cases in dedicated cmd/root_chdir_test.go file
• Update global flags documentation with examples
• Create blog post announcing the feature

why

• Enables using development builds of Atmos to work with infrastructure repositories without manipulating shell environment
• Simplifies CI/CD workflows by avoiding directory changes in scripts
• Provides consistent interface similar to other CLI tools (make, git, etc.)
• Improves developer experience when working with multiple infrastructure repositories
• Establishes idiomatic Go testing pattern for all cmd package tests
• Prevents test pollution from global RootCmd state that was causing mysterious test failures
• Fixes misleading "file not found" errors when config paths are actually empty

references

• Addresses use case: Using development Atmos binaries to point at other infrastructure repos without changing directories manually
• Flag processes before all other operations including config loading
• CLI flag takes precedence over environment variable
• Comprehensive error handling for invalid paths, non-existent directories, and file paths
• TestKit pattern follows Go 1.15+ testing.TB interface idiom similar to t.Setenv() and t.Chdir()

testing

Chdir Flag Tests

• 15+ test cases in dedicated cmd/root_chdir_test.go file (separated to comply with file length lint rules)
• Test coverage includes:
  • Absolute and relative paths
  • Short (-C) and long (--chdir) flag forms
  • Environment variable usage and precedence
  • Error conditions (invalid paths, non-existent directories, files)
  • Integration with config loading and base-path
  • Edge cases (symlinks, paths with spaces, parent directory references)

Test Isolation & TestKit

• Implemented cmd.NewTestKit(t) wrapper following Go 1.15+ testing.TB interface pattern
• Migrated all 55 test cleanup calls across 21 test files from CleanupRootCmd to TestKit
• Comprehensive TestKit tests covering:
  • Automatic cleanup functionality
  • testing.TB interface compliance
  • Table-driven test patterns
  • Nested test scenarios
  • StringSlice flag corruption prevention
• Net reduction of 248 lines while improving maintainability

Test Results

• All chdir-specific tests pass successfully
• All cmd package tests migrated to TestKit pattern
• Linting passes with 0 issues
• Build succeeds
• Refactored complex nested blocks to comply with nestif linter rules

documentation

• Updated website/docs/cli/global-flags.mdx with flag description, usage, and examples
• Created website/blog/2025-01-15-chdir-flag.md announcing the feature
• Updated CLAUDE.md with TestKit pattern as the standard for all cmd tests
• Examples include:
  • Development workflows with local Atmos builds
  • CI/CD pipelines with multiple directories
  • Multi-repository infrastructure management
  • Scripting automation

technical details

TestKit Implementation

• Wraps testing.TB interface for composable test helpers
• Automatic RootCmd snapshot/restore via t.Cleanup()
• Works seamlessly with subtests and table-driven tests
• Handles StringSlice flag corruption using reflection to clear underlying slice
• All testing.TB methods pass through: Helper(), Log(), Setenv(), Cleanup(), etc.

Error Message Improvements

• Changed misleading "file not found" errors to show actual empty paths
• Distinguish between "does not exist" and other stat errors (permission denied, etc.)
• Include actual file/directory path in all error messages for clarity

Code Quality

• Deleted CleanupRootCmd and WithRootCmdSnapshot (never in main)
• Single idiomatic pattern across entire test suite
• Reduced code duplication and improved maintainability
• All pre-commit hooks passing

Summary by CodeRabbit

• New Features

  • Added global --chdir / -C flag to run Atmos as if started in a specified directory; flag takes precedence over ATMOS_CHDIR and is applied before config loading.

• Documentation

  • Added CLI docs and a blog post with usage, examples, and guidance on combining --chdir with --base-path; CLI help updated to show the flag.

• Bug Fixes / Validation

  • Improved path/file validation with clearer error messages for missing, non-directory, or inaccessible paths.

• Tests

  • Extensive new tests and a test harness ensuring isolated, deterministic CLI and working-directory behavior.

what

• Comprehensive performance optimizations for Atmos achieving 5.2x (420%) faster execution and 92% memory reduction
• Additional optimizations for atmos describe affected command achieving 70-85% performance improvement

why

• Large-scale infrastructure configurations with hundreds of stacks and thousands of components experience slow processing times
• High memory usage limits scalability and increases CI/CD costs
• The atmos describe affected command was particularly slow when processing many stacks in CI/CD pipelines
• Sequential processing and repeated file operations created bottlenecks

Performance Results

Core Atmos Operations (760 YAML files, 533 stacks, 8k components)

• Execution time: 16 seconds → 3 seconds (5.2x faster, 80.9% reduction)
• Heap allocations: 4.8 GB → 385 MB (92% reduction)
• CPU utilization: ~180% → 261% (improved multi-core usage)

atmos describe affected Command

• Overall improvement: 70-85% faster execution time
• Parallel processing gain: 40-60% improvement from concurrent stack processing
• File indexing gain: 60-80% reduction in PathMatch operations
• Combined optimizations: Multiplicative performance improvements across all operations

Optimization Strategies

1. Algorithm Optimizations

• O(1) YAML tag lookup replacing O(n) searches
• Optimized deep merge operations reducing redundant checks
• Early exit for custom tags preventing unnecessary processing
• Custom deep comparison (15-25% faster than reflect.DeepEqual)

2. Caching Optimizations

• Inheritance caching - Prevents recomputation of component inheritance chains
• Parsed YAML caching - Reuses parsed YAML documents across operations
• FindStacksMap caching - Caches expensive stack map operations
• JSON schema compilation caching - Reuses compiled validation schemas
• PathMatch caching - Caches glob pattern matching results
• Sprig function caching - Memoizes expensive template function results
• String interning - Reduces memory for duplicate strings
• **Compone...

• Replaced telemetry.IsCI() checks in authentication logic with a isInteractive() function that checks for TTY availability.
• Modified pkg/telemetry/ci.go to require both JENKINS_URL and BUILD_ID to be present for Jenkins CI detection, preventing false positives when only JENKINS_URL is set.
• Updated the AWS SSO device authorization prompt message to correctly state "verify code" instead of "enter code".
• Added debug logging to pkg/telemetry/ci.go for better visibility into CI detection.
• Configured AWS SDK to explicitly use aws.AnonymousCredentials{} when loading config for SSO, preventing hangs on default credential providers.

why

• Runtime vs. Telemetry Separation: Previously, telemetry.IsCI() was used for runtime behavior decisions (e.g., showing interactive prompts). This is incorrect as telemetry functions should not dictate application behavior. The change separates these concerns by using isInteractive() for runtime decisions and improving CI detection accuracy.
• False Jenkins Detection: The JENKINS_URL environment variable was being set by build-harness by default, leading to incorrect Jenkins CI detection in environments that were not actual Jenkins CI. Requiring both JENKINS_URL and BUILD_ID for Jenkins detection resolves this false positive.
• Accurate User Guidance: The AWS SSO device flow requires users to verify a code displayed in the terminal against the browser prompt, not enter it. The message has been updated for clarity.
• Preventing Authentication Hangs: In non-interactive environments (like make targets without a TTY), the authentication flow was hanging because it was waiting for terminal input that would never arrive. The isInteractive() check ensures prompts are only shown when a TTY is available. Explicitly providing aws.AnonymousCredentials{} for SSO config loading prevents the AWS SDK from attempting to find credentials from other sources that might hang.

False Jenkins Detection

• CloudPosse build-harness sets JENKINS_URL=https://localhost/buildByToken/buildWithParameters by default
• Old detection only checked JENKINS_URL existence → false positives in any project using build-harness
• Changed to require both JENKINS_URL AND BUILD_ID (what real Jenkins sets)
• Prevents false CI detection when running atmos auth login in make targets

Pre-commit Build Issues

• Building custom-gcl during pre-commit can cause git corruption in worktrees
• Changed to check for pre-built binary and fail with helpful message instead
• Users run make custom-gcl once, then commits work without rebuilding

references

• Related to build-harness Jenkins URL: https://github.com/cloudposse/build-harness/blob/master/modules/jenkins/Makefile#L17

Summary by CodeRabbit

• Bug Fixes

  • AWS SSO device authentication prompts now correctly show instructions, URL and code, and will attempt to open the browser in interactive sessions; non-interactive sessions return clear errors.

• Refactor

  • Authentication flow now uses interactive terminal detection instead of CI-only checks.
  • CI detection enhanced with more comprehensive environment-variable handling and additional debug logging.

• Tests

  • Added stdin TTY mock support for testing interactive behavior.

• Chores

  • Updated lint/build scripts and Makefile steps with clearer user-facing messages and a new run script.

why

• Improve user experience with cleaner, more readable version output
• Make release information more accessible with markdown-rendered titles
• Ensure proper display across different terminal widths
• Provide visual feedback during network operations
• Follow Atmos architectural patterns with self-contained command packages
• Enable better testing through interface-based design
• Support standard Atmos environment variable conventions

references

• Related to version command improvements
• Follows command registry pattern documented in docs/prd/command-registry-pattern.md

Summary by CodeRabbit

• New Features

  • New version commands: list and show — interactive spinner (TTY) with non‑TTY fallback, text/JSON/YAML outputs, pagination, date filtering, prerelease options, current-version indicators, markdown-rendered titles, platform-aware asset listings and tables.

• Authentication

  • GitHub token handling now prefers ATMOS_GITHUB_TOKEN over GITHUB_TOKEN and is bound earlier during startup.

• Errors

  • New clear sentinels for rate limits, invalid limits/offsets, unsupported formats, narrow terminals, and spinner failures.

• Documentation

  • PRDs, usage guides, and a blog post for the new commands.

• Tests

  • Extensive unit and integration tests for list/show, formatters, GitHub client, and edge cases.

• Chores

  • Increased cache lock retry attempts.

• Introduced a new utility module (pkg/auth/cloud/aws/env.go) to manage the isolation of problematic AWS environment variables during authentication.
• Created WithIsolatedAWSEnv() function that temporarily clears a predefined list of AWS environment variables, executes a provided function, and then restores the original values.
• Created LoadIsolatedAWSConfig() which wraps AWS SDK's config.LoadDefaultConfig() and utilizes WithIsolatedAWSEnv() to ensure environment variables do not interfere with AWS config loading.
• Updated all AWS authentication and identity creation code paths to use LoadIsolatedAWSConfig() instead of config.LoadDefaultConfig() when initializing AWS SDK clients. This includes:
  • pkg/auth/identities/aws/assume_role.go
  • pkg/auth/identities/aws/permission_set.go
  • pkg/auth/identities/aws/user.go
  • pkg/auth/providers/aws/saml.go
  • pkg/auth/providers/aws/sso.go
• Added debug logging to report which AWS environment variables are being ignored during authentication when they are set externally.
• Added comprehensive unit and integration tests to cover the environment isolation logic, including scenarios with set, unset, and partially set variables, error handling, and the new logging functionality.

why

• Resolves DEV-3706: Previously, external AWS environment variables (like AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE) could interfere with Atmos's internal AWS authentication mechanisms, particularly when using AWS IAM Identity Center (SSO) or assuming roles. This often led to authentication failures or unexpected behavior.
• Ensures Consistent Authentication: By isolating these environment variables during the authentication process, Atmos can reliably use its own credential management and configuration without external interference, regardless of the user's shell environment.
• Improves User Experience: Provides transparency by logging which environment variables are being ignored during authentication, without exposing sensitive values.
• Maintains Backward Compatibility: The internal/aws_utils/aws_utils.go file, which is used in contexts where external environment variables are expected to be honored (e.g., Terraform backend configuration), continues to use config.LoadDefaultConfig() to avoid breaking existing functionality.

references

• closes #123
• DEV-3706: https://linear.app/cloudposse/issue/DEV-3706
• AWS SDK Go v2 Configuration: https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/environment-variables/

Summary by CodeRabbit

• New Features

  • Added an AWS environment isolation utility to prevent external AWS env vars from affecting authentication flows.
  • Switched AWS config loading throughout SSO, assume-role, STS and session-token flows to use the isolated loader.

• Tests

  • Added comprehensive tests verifying env var isolation, restoration after use, error handling, and successful authentication despite external AWS env vars.

• Replaced manual mock implementation of storer.Storer with a mock generated by mockgen in internal/exec/describe_affected_utils_test.go.
• Enhanced the test in internal/exec/template_funcs_test.go to more thoroughly validate the FuncMap and the returned AtmosFuncs instanc...

what

• Improved the heatmap performance on Docker, fixed critical performance issues with the --heatmap flag in Docker environments
• Renamed "Total" column to "CPU Time" throughout the performance heatmap display to clarify that it represents sum of self-times, not wall-clock time
• Added parallelism metric to both console and TUI displays showing CPU Time ÷ Elapsed ratio
• Improved TUI visualizations (bar chart and sparkline modes) to display average time per call instead of total CPU time for better user comprehension
• Enhanced TUI legend with live performance metrics (Parallelism, Elapsed time, CPU Time) displayed at the top
• Split TUI legend into three lines for improved readability
• Updated comprehensive documentation in website/docs/troubleshoot/profiling.mdx with explanations of all new metrics and display formats

why

Docker performance context

This PR improved the heatmap performance on Docker, fixed critical performance issues with the --heatmap flag in Docker environments.

The Docker Problem:

• Commands with --heatmap took ~60 seconds to start in Docker containers (vs instantly on macOS)
• Root cause: runtime.Stack() was called on every tracked function to get goroutine IDs
• In Docker, this syscall is significantly slower than on native macOS
• With thousands of tracked function calls during stack processing, overhead accumulated to ~1 minute

The Solution:

• Introduced "simple tracking mode" using a single global call stack instead of per-goroutine tracking
• Avoids expensive runtime.Stack() calls for single-goroutine execution (most Atmos commands)
• Result: ~19x faster (119µs vs 3ms for 1000 calls)

TUI improvements

Problem 1: Confusing Column Name
The "Total" column name was ambiguous - users couldn't tell if it meant wall-clock time or CPU time. This caused confusion when trying to interpret performance data.

Problem 2: Missing Parallelism Context
Users had no way to understand the relationship between CPU time and elapsed time. When CPU time exceeded elapsed time (e.g., 5 minutes of CPU time in 22 seconds), it looked wrong but was actually correct for parallel execution.

Problem 3: TUI Display Showed Confusing Values
The bar chart displayed large total times (e.g., "2m47s") for functions called hundreds of thousands of times, making it appear slow when the average time per call was actually fast (e.g., 0.37ms). This was mathematically correct but user-unfriendly.

Problem 4: Cramped Legend
The single-line legend was too wide and difficult to read in the TUI.

Solutions

Solution 1: Clear Terminology
Renamed "Total" to "CPU Time" everywhere with consistent explanations that it represents "sum of self-time (excludes children)" to avoid confusion with wall-clock time.

Solution 2: Parallelism Metric
Added parallelism calculation and display in both console output and TUI legend:

• Format: Parallelism: ~0.9x (single-threaded) or ~58.2x (highly parallel)
• Helps users immediately understand execution characteristics
• Values less than 1.0 indicate single-threaded execution
• Values greater than 1.0 indicate parallel execution across multiple cores

Solution 3: User-Friendly TUI Visualizations
Changed bar chart and sparkline displays from showing total CPU time to showing average time per call with call counts:

• Old format: 2m47.818679s (×447586) - confusing
• New format: avg: 0.37ms | calls: 447586 - intuitive
• Bar length still represents total CPU time (overall impact)
• Average time shows typical function performance

Solution 4: Multi-Line Legend
Split the TUI legend into three informative lines:

• Line 1: Live metrics (Parallelism, Elapsed, CPU Time)
• Line 2: Explanation of Count and CPU Time columns
• Line 3: Explanation of statistical timing columns (Avg, Max, P95)

example

testing

All existing tests pass:

• ✅ 26 tests in pkg/perf package
• ✅ 36 tests in pkg/ui/heatmap package
• ✅ 87 tests in cmd package
• ✅ Total: 149 tests across all modified packages

Manual verification:

• Compiled binary successfully on macOS
• Tested in Docker
• Verified console output shows new format with parallelism
• Confirmed interactive TUI displays updated legend
• Website documentation builds without errors
• Docker performance remains fast (1-2 second startup with --heatmap)

documentation

Updated website/docs/troubleshoot/profiling.mdx with:

• New "Interactive TUI Legend" section explaining the 3-line legend format
• Updated Performance Summary section with Parallelism explanation
• Updated all column descriptions (CPU Time instead of Total)
• Enhanced Bar Chart and Sparkline mode descriptions with new display format
• Added concrete examples showing the new avg: Xms | calls: N format

benefits

1. Clearer Metrics: "CPU Time" is unambiguous compared to "Total"
2. Execution Context: Parallelism metric immediately shows if execution was single-threaded or parallel
3. Intuitive Display: Average times per call are much easier to understand than large totals
4. Better UX: Multi-line legend is more readable and informative
5. Complete Documentation: Users have clear explanations of all metrics
6. Backward Compatible: All existing tests pass without changes
7. Docker Ready: Works fast in Docker environments (builds on PR #1611 improvements)

Summary by CodeRabbit

• New Features

  • Heatmap and summaries now show CPU Time and Parallelism; charts and sparklines show average time per call with counts; interactive UI supports cancellation and a new toggle to control tracking mode.

• Bug Fixes

  • More accurate CPU Time and parallelism calculations; per-function CPU Time shown; durations truncated to microseconds; headers and columns reorganized for clarity.

• Tests

  • Added tests for tracking modes, performance comparisons, and legend/render output; Windows skips and more robust environment/IO handling.

• Documentation

  • Profiling docs updated to explain CPU Time vs Self‑Time with revised examples.

• Chores

  • CI tool version bumped and test cleanup/synchronization improvements.

what

• Add log.Trace() calls for all squelched errors throughout the codebase
• Update logging documentation to include squelched error handling guidance
• Update error handling strategy PRD to document squelched error patterns

why

• Ensures no errors are silently lost, even when intentionally ignored
• Provides complete error visibility during debugging with --logs-level=Trace
• Establishes clear patterns for handling non-critical errors

details

Code Changes (19 files)

Added trace logging for squelched errors in:

• Configuration binding: Environment variables and flags (viper.BindEnv(), viper.BindPFlag())
• File cleanup: Temporary file and directory removal (os.Remove(), os.RemoveAll())
• Resource closing: File handles, clients, connections (Close())
• Lock operations: File locks in defer statements (Unlock())
• UI operations: Terminal output, command help (fmt.Fprint(), cmd.Help())
• Performance tracking: Histogram value recording
• Cache operations: Non-critical cache file operations on Windows

Patterns Applied

// ❌ WRONG: Silent error squelching
_ = os.Remove(tempFile)

// ✅ CORRECT: Log squelched errors at Trace level
if err := os.Remove(tempFile); err != nil && !os.IsNotExist(err) {
    log.Trace("Failed to remove temporary file during cleanup", "error", err, "file", tempFile)
}

Special Cases

• Defer statements: Capture errors in closures for logging
• File existence checks: Use os.IsNotExist() to avoid logging expected conditions
• Log file cleanup: Use fmt.Fprintf(os.Stderr, ...) to avoid logger recursion

Documentation Updates

• docs/logging.md: Added comprehensive "Squelched Errors" section with patterns and examples
• docs/prd/error-handling-strategy.md: Added "Squelched Error Handling" section with guidelines and code examples

references

• Related to overall error handling and logging strategy
• All changes compile and pass pre-commit hooks

Summary by CodeRabbit

• Bug Fixes

  • Prevented silent failures by adding error handling and trace-level logging across command flags, env bindings, config parsing, file cleanup, network response closing, metrics recording, and TUI rendering.
  • Improved cleanup reliability by logging non-fatal errors during temporary file/dir removal and resource closure.

• Refactor

  • Standardized logging for squelched (non-fatal) errors, replacing ignored returns with guarded paths without changing core behavior.

• Documentation

  • Expanded logging guidance with a new “Squelched Errors” section, examples, patterns, and best practices.
  • Updated error-handling strategy to include when and how to log squelched errors.

what

• Fix --heatmap flag not working with terraform, helmfile, and packer commands
• Implement advanced performance tracking with self-time vs total-time separation
• F...

why

• Ensures no errors are silently lost, even when intentionally ignored
• Provides complete error visibility during debugging with --logs-level=Trace
• Establishes clear patterns for handling non-critical errors

details

Code Changes (19 files)

Added trace logging for squelched errors in:

• Configuration binding: Environment variables and flags (viper.BindEnv(), viper.BindPFlag())
• File cleanup: Temporary file and directory removal (os.Remove(), os.RemoveAll())
• Resource closing: File handles, clients, connections (Close())
• Lock operations: File locks in defer statements (Unlock())
• UI operations: Terminal output, command help (fmt.Fprint(), cmd.Help())
• Performance tracking: Histogram value recording
• Cache operations: Non-critical cache file operations on Windows

Patterns Applied

// ❌ WRONG: Silent error squelching
_ = os.Remove(tempFile)

// ✅ CORRECT: Log squelched errors at Trace level
if err := os.Remove(tempFile); err != nil && !os.IsNotExist(err) {
    log.Trace("Failed to remove temporary file during cleanup", "error", err, "file", tempFile)
}

Special Cases

• Defer statements: Capture errors in closures for logging
• File existence checks: Use os.IsNotExist() to avoid logging expected conditions
• Log file cleanup: Use fmt.Fprintf(os.Stderr, ...) to avoid logger recursion

Documentation Updates

• docs/logging.md: Added comprehensive "Squelched Errors" section with patterns and examples
• docs/prd/error-handling-strategy.md: Added "Squelched Error Handling" section with guidelines and code examples

references

• Related to overall error handling and logging strategy
• All changes compile and pass pre-commit hooks

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Prevented silent failures by adding error handling and trace-level logging across command flags, env bindings, config parsing, file cleanup, network response closing, metrics recording, and TUI rendering.
  • Improved cleanup reliability by logging non-fatal errors during temporary file/dir removal and resource closure.

• Refactor

  • Standardized logging for squelched (non-fatal) errors, replacing ignored returns with guarded paths without changing core behavior.

• Documentation

  • Expanded logging guidance with a new “Squelched Errors” section, examples, patterns, and best practices.
  • Updated error-handling strategy to include when and how to log squelched errors.

atmos describe stacks --heatmap

atmos terraform plan vpc -s uw2-prod --heatmap

why

Heatmap Flag Fix

The --heatmap flag was not working for terraform, helmfile, and packer commands because:

• These commands use DisableFlagParsing = true to pass native flags through to underlying tools
• When flag parsing is disabled, Cobra doesn't parse the --heatmap flag
• The PersistentPreRun hook couldn't detect the flag via cmd.Flags().GetBool("heatmap")
• Performance tracking was never enabled, so no data collected

Performance Tracking Enhancement

--heatmap showed inconsistent timing metrics for long-running commands:

• Elapsed time was correct
• Individual function totals were massively inflated (- approximately 1,890x inflation)
• Root cause: Unable to show accurate call counts for recursive functions without timing inflation

Requirement: Show true call volume (e.g., 1,890 calls) with accurate timing (no inflation) and consistent metrics.

changes

Advanced Performance Tracking (Self-Time vs Total-Time)

Implemented professional-grade profiling metrics that separate:

• Total time (wall-clock): Includes time spent in child function calls
• Self-time: Actual work done in the function, excluding children
• Accurate recursive tracking: Shows ALL calls including recursive ones with correct timing

Key Features:

1. Goroutine-local call stack tracking - Each goroutine maintains its own call stack
2. Child time accumulation - Each stack frame tracks time spent in children
3. Self-time calculation - selfTime = totalTime - childTime
4. HDR Histogram on self-time - P95 based on actual work, not wall-clock
5. Direct recursive tracking - No wrapper pattern needed, tracks every call accurately

Benefits:

• Accurate recursive tracking: Shows true call counts (e.g., 1,890 calls) with correct timing
• No inflation: Self-time excludes child execution, total-time includes it
• Better insights: Identify where time is spent (total) vs where work is done (self-time)
• Professional profiling: Same metrics as pprof, but function-level and easier to use

Example Output:

Function                                 Count    Total      Avg        Max        P95
utils.processCustomTags                  1024     4.27ms     4µs        146µs      15µs

• Count: 1024 - ALL calls including recursive ones
• Total: 4.27ms - wall-clock time including all children
• Avg: 4µs - average self-time per call (actual work only)
• Max: 146µs - maximum self-time for a single call (excludes children)
• P95: 15µs - 95th percentile of self-time

Metric Consistency Fix

Changed Max to track self-time instead of total-time:

• All three metrics (Avg, Max, P95) consistently track self-time
• Rationale: Enables accurate comparison between metrics for identifying performance outliers

TUI Legend

Added informative legend to heatmap TUI:

Count: # calls (incl. recursion) | Total: wall-clock (incl. children & recursion) |
Avg: avg self-time | Max: max self-time | P95: 95th percentile self-time

• Appears after the header in all visualization modes
• Explains what each metric means
• Clarifies that Count and Total include recursion
• Helps users understand self-time vs total-time

Recursive Function Updates

Benefits:

• Shows true call volume (e.g., 1,024 calls instead of 1)
• Timing remains accurate via self-time calculation
• No wrapper pattern complexity needed

Documentation

Updated profiling documentation:

• "Understanding Total vs Self-Time" tip reflects that all three metrics now track self-time
• Updated metric descriptions with accurate explanations
• Added examples showing self-time context for outlier detection

Heatmap Flag Improvements

• Added helper function to manually parse --heatmap from os.Args for commands with DisableFlagParsing = true
• Integrated heatmap flag detection in terraform, helmfile, and packer commands
• Added test coverage for heatmap flag detection

Enhanced Performance Tracking Coverage

• Added perf.Track() to UnmarshalYAMLFromFile to track YAML parsing performance
• Ensures complete visibility into YAML processing call chains during merge operations

testing

Performance Tracking Tests

New self-time tracking tests:

1. TestSelfTimeVsTotalTime - Verifies self-time excludes child time
2. TestNestedFunctionSelfTime - Tests multi-level nesting (grandparent → parent → child)
3. TestDirectRecursionWithSelfTime - Tests direct recursion with accurate counts AND timing

Updated existing tests:

• All 20 perf tests passing ✅
• Tests verify self-time calculation accuracy for all three metrics (Avg, Max, P95)

Recursive function tests:

1. TestRecursiveFunctionTracking - Wrapper pattern verification
2. TestRecursiveFunctionWrongPattern - Demonstrates inflation with wrong pattern
3. TestMultipleRecursiveFunctionsIndependent - Independent function tracking
4. TestYAMLConfigProcessingRecursion - YAML import hierarchy (50 levels deep)
5. TestYAMLConfigProcessingMultipleImports - Fan-out import pattern
6. TestProcessBaseComponentConfigRecursion - Component inheritance (15 levels deep)

Heatmap UI Tests

Updated heatmap tests:

• Updated legend verification tests
• All 36 heatmap tests passing ✅

Heatmap Flag Tests

✅ TestTerraformHeatmapFlag passes successfully
✅ Manual testing confirms --heatmap works with:

• atmos terraform plan <component> -s <stack> --heatmap
• atmos helmfile <subcommand> <component> -s <stack> --heatmap
• atmos packer <subcommand> <component> -s <stack> --heatmap

Build Verification

✅ All linter checks passing (golangci-lint)
✅ Full project builds successfully
✅ Website documentation builds without errors
✅ All 56 tests passing (20 perf + 36 heatmap)

expected impact

For Recursive Functions

• Before: C...

what

• Code Refactoring: Extracted common component processing logic into reusable helper functions, eliminating ~991 lines of duplicated code
• Auth Section Deep-Merging: Implemented complete deep-merge support for auth section following the same hierarchy as vars/env/settings:
  • Global → Component-Type-Specific → Base Component → Component → Overrides
  • Supports all three component types: Terraform, Helmfile, and Packer
  • Consistent with existing section merge behavior
• Comprehensive Testing: Created extensive test coverage for all new helper functions with 29 test cases

why

• The ProcessStackConfig function contained nearly identical logic repeated 3 times for Terraform, Helmfile, and Packer components
• This duplication made the codebase harder to maintain, more error-prone, and difficult to extend
• The auth section needed proper deep-merge support to enable hierarchical authentication configuration across the stack
• Centralized logic improves code quality, maintainability, and makes future enhancements easier
• Better test coverage ensures reliability and prevents regressions

changes

Auth Section Deep-Merge Implementation

Merge Hierarchy

The auth section now merges through the complete hierarchy (later values override earlier ones):

1. Global auth (auth: at stack root)
2. Component-type-specific auth (terraform.auth:, helmfile.auth:, or packer.auth:)
3. Base component auth (from component: inheritance)
4. Component auth (component-specific auth:)
5. Component overrides auth (overrides.auth:)

Test Coverage

• All existing test cases updated with auth fields
• Auth assertion added to test validation
• Tests verify auth merges correctly through the hierarchy
• ✅ All tests passing

Comprehensive test coverage with:

• TestProcessComponent

  • Terraform component with all sections
  • Helmfile component without Terraform-specific sections
  • Packer component
  • Component with overrides
  • Component with inheritance
  • Invalid configuration error cases

• TestProcessTerraformBackend

  • S3, GCS, Azure backend processing
  • Base component name handling
  • Backend type precedence
  • Path normalization (component names with slashes)

• TestProcessTerraformRemoteStateBackend

  • Inheritance from backend type
  • Type precedence rules
  • Section merging

• TestMergeComponentConfigurations

  • All component types (Terraform, Helmfile, Packer)
  • Base component handling
  • Abstract component special processing
  • Auth section merging validation

• TestProcessAuthConfig

  • Auth configuration merging

testing

Test Results

✅ All new test cases pass
✅ All auth merging tests pass

Test Quality

• Table-driven test pattern
• Real behavior testing (not stub/tautological)
• Comprehensive coverage of happy paths and error cases
• Clear test names describing expected behavior
• Proper error validation
• Auth section merge hierarchy fully tested

Auth Section Usage Examples

# Stack manifest: stacks/catalog/vpc.yaml

# Global auth (applies to all components)
auth:
  aws:
    profile: default-profile
    region: us-east-1

# Terraform-specific auth (applies to all Terraform components)
terraform:
  auth:
    aws:
      profile: terraform-profile

components:
  terraform:
    vpc:
      # Component-specific auth
      auth:
        aws:
          profile: vpc-specific-profile

Result: The final merged auth for the vpc component will be:

auth:
  aws:
    profile: vpc-specific-profile  # From vpc.auth (highest precedence)
    region: us-east-1              # From global auth (merged in)

# Stack manifest: stacks/catalog/vpc.yaml

# Global auth (applies to all components)
auth:
  aws:
    profile: default-profile
    region: us-east-1

# Terraform-specific auth (applies to all Terraform components)
terraform:
  auth:
    aws:
      profile: terraform-profile

components:
  terraform:
    vpc:
      # Component-specific auth
      auth:
        aws:
          profile: vpc-specific-profile
      
# Override auth takes highest precedence
overrides:
  auth:
    aws:
      profile: override-profile

Result: The final merged auth for the vpc component will be:

auth:
  aws:
    profile: override-profile  # From overrides.auth (highest precedence)
    region: us-east-1          # From global auth (merged in)

notes

✅ Auth deep-merge implementation complete

• Full hierarchy support: Global → Component-Type → Base → Component → Overrides
• Consistent with vars/env/settings merge behavior
• All errors properly wrapped with static errors
• Comprehensive test coverage

Current status:

• ✅ Code refactoring complete
• ✅ Auth section deep-merge complete
• ✅ Test coverage complete
• ✅ Error wrapping complete
• ✅ Backward compatibility verified

Summary by CodeRabbit

• New Features

  • Richer stack/component processing: deeper merges for vars/settings/env/auth, base-component auth support, inheritance and overrides resolution, and unified per-stack component assembly.
  • Terraform backend & remote-state handling with sensible defaults and generated state keys for S3/GCS/Azure.

• Improvements

  • More granular, standardized error signaling for invalid manifest sections and clearer provenance for imports.
  • New utilities to process stack manifests and query component relationships.

• Chores

  • Dependency version bumps for stability.

• Tests

  • Expanded unit test coverage across stack processing, merging, inheritance, overrides, and backend resolution.

what

Introduce a complete authentication system for Atmos, enabling secure multi-cloud authentication with support for AWS IAM Identity Center (SSO), SAML providers, assume role chains, and AWS user credentials. The system provides seamless integration with Terraform workflows while maintaining isolation from users' existing AWS configurations.

Features

Authentication Providers

• AWS IAM Identity Center (SSO) - Full SSO integration with session management
• AWS SAML - Browser-based SAML authentication with MFA support (Google Apps, Okta, ADFS)
• AWS Assume Role - Cross-account role assumption capabilities
• AWS User - Direct AWS access key authentication with MFA support

Identity Chaining

• Sequential authentication flows (e.g., SSO → Permission Set → Assume Role)
• Recursive provider resolution through identity chains
• Circular dependency detection and prevention

CLI Commands

• atmos auth login - Interactive authentication with identity selection
• atmos auth whoami - Display current authentication status
• atmos auth env - Export environment variables (export, json, dotenv formats)
• atmos auth exec - Execute commands with authentication context
• atmos auth validate - Comprehensive configuration validation
• atmos auth user configure - AWS user credential configuration

AWS Integration

• Isolated credential files: ~/.aws/atmos//credentials
• Separate config files: ~/.aws/atmos//config
• Automatic environment variable management (AWS_PROFILE, AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE)
• Terraform prehook integration for seamless workflow execution
• User's existing AWS files remain untouched

Architecture

Layout

internal/auth/
├── manager.go              # Core authentication manager
├── interfaces.go           # Core interfaces and types
├── factory.go             # Provider/identity factory functions
├── providers/aws/         # AWS authentication providers
│   ├── sso.go            # IAM Identity Center provider
│   ├── saml.go           # SAML provider with browser automation
│   └── assume_role.go    # Assume role provider
├── identities/aws/        # AWS identity implementations
│   ├── permission_set.go # Permission set identity
│   ├── assume_role.go    # Assume role identity
│   └── user.go           # AWS user identity
├── credentials/           # Secure credential storage
├── environment/           # AWS file management
├── config/               # Configuration merging
└── validation/           # Configuration validation

why

Atmos Auth allows us to simplify our reference architecture and helps assist with consolidating the toolset that the typical DevOps user needs to manage Terraform.

Summary by CodeRabbit

• New Features

  • Introduces a full "auth" CLI (validate, login, whoami, env [bash/json/dotenv], exec, user configure), per-component auth merging, Terraform --identity (-i) option, Terraform auth pre-hooks, demo-auth example, credential/keyring store, and AWS file helpers.

• Documentation

  • Full Auth docs: architecture, user guide, CLI reference, examples and demo.

• Tests

  • Extensive unit, integration and snapshot coverage for auth flows, providers, identities, hooks and CLI.

• Bug Fixes

  • Unified cross-platform URL opener; docs-open message now printed to stderr.

what

• Add support for Go's -short flag to skip long-running tests (>2 seconds)
• Enable faster develo...