feat: Add .env file support (DEV-2990)

cmd/auth_exec.go

@@ -110,7 +110,7 @@ func executeAuthExecCommandCore(cmd *cobra.Command, args []string) error {
 
 	// Prepare shell environment with file-based credentials.
 	// Start with current OS environment + global env from atmos.yaml and let PrepareShellEnvironment configure auth.
-	baseEnv := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.Env)
+	baseEnv := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.GetCaseSensitiveEnvVars())
 	envList, err := authManager.PrepareShellEnvironment(ctx, identityName, baseEnv)
 	if err != nil {
 		return fmt.Errorf("failed to prepare command environment: %w", err)

cmd/cmd_utils.go

@@ -572,7 +572,7 @@ func executeCustomCommand(
 		// Prepare ENV vars
 		// ENV var values support Go templates and have access to {{ .ComponentConfig.xxx.yyy.zzz }} Go template variables
 		// Start with current environment + global env from atmos.yaml to inherit PATH and other variables.
-		env := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.Env)
+		env := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.GetCaseSensitiveEnvVars())
 		for _, v := range commandConfig.Env {
 			key := strings.TrimSpace(v.Key)
 			value := v.Value
@@ -629,7 +629,7 @@ func executeCustomCommand(
 		commandName := fmt.Sprintf("%s-step-%d", commandConfig.Name, i)
 
 		// Pass the prepared environment with custom variables to the subprocess
-		err = e.ExecuteShell(commandToRun, commandName, workDir, env, false)
+		err = e.ExecuteShell(&atmosConfig, commandToRun, commandName, workDir, env, false)
 		errUtils.CheckErrorPrintAndExit(err, "", "")
 	}
 }

internal/exec/shell_utils.go

@@ -20,6 +20,7 @@ import (
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/schema"
+	"github.com/cloudposse/atmos/pkg/ui"
 	"github.com/cloudposse/atmos/pkg/ui/theme"
 	u "github.com/cloudposse/atmos/pkg/utils"
 )
@@ -48,9 +49,28 @@ func ExecuteShellCommand(
 	}
 
 	cmd := exec.Command(command, args...)
-	// Build environment: os.Environ() + global env (atmos.yaml) + command-specific env.
-	// Global env has lowest priority after system env, command-specific env overrides both.
-	cmdEnv := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.Env)
+	// Build environment: os.Environ() + global env (atmos.yaml) + working dir .env + command-specific env.
+	// Global env has lowest priority after system env, command-specific env overrides all.
+	cmdEnv := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.GetCaseSensitiveEnvVars())
+
+	// Load working directory .env files if enabled.
+	if atmosConfig.Env.Files.Enabled && dir != "" {
+		dirEnv, loadedFiles, err := envpkg.LoadFromDirectory(
+			dir,
+			atmosConfig.Env.Files.Paths,
+			atmosConfig.Env.Files.Parents,
+			atmosConfig.BasePath,
+		)
+		if err != nil {
+			log.Debug("Failed to load .env files from working directory", "dir", dir, "error", err)
+		} else {
+			for _, file := range loadedFiles {
+				ui.Success(fmt.Sprintf("Loaded %s", filepath.Base(file)))
+			}
+			cmdEnv = envpkg.MergeEnvSlices(cmdEnv, envpkg.MapToSlice(dirEnv))
+		}
+	}
+
 	cmdEnv = append(cmdEnv, env...)
 	cmdEnv = append(cmdEnv, fmt.Sprintf("ATMOS_SHLVL=%d", newShellLevel))
 	cmd.Env = cmdEnv
@@ -111,13 +131,14 @@ func ExecuteShellCommand(
 
 // ExecuteShell runs a shell script.
 func ExecuteShell(
+	atmosConfig *schema.AtmosConfiguration,
 	command string,
 	name string,
 	dir string,
 	envVars []string,
 	dryRun bool,
 ) error {
-	defer perf.Track(nil, "exec.ExecuteShell")()
+	defer perf.Track(atmosConfig, "exec.ExecuteShell")()
 
 	newShellLevel, err := u.GetNextShellLevel()
 	if err != nil {
@@ -130,6 +151,30 @@ func ExecuteShell(
 	// This matches the behavior before commit 9fd7d156a where the environment
 	// was merged rather than replaced.
 	mergedEnv := os.Environ()
+
+	// Merge global env from atmos.yaml if atmosConfig is provided.
+	if atmosConfig != nil {
+		mergedEnv = envpkg.MergeGlobalEnv(mergedEnv, atmosConfig.GetCaseSensitiveEnvVars())
+
+		// Load working directory .env files if enabled.
+		if atmosConfig.Env.Files.Enabled && dir != "" {
+			dirEnv, loadedFiles, err := envpkg.LoadFromDirectory(
+				dir,
+				atmosConfig.Env.Files.Paths,
+				atmosConfig.Env.Files.Parents,
+				atmosConfig.BasePath,
+			)
+			if err != nil {
+				log.Debug("Failed to load .env files from working directory", "dir", dir, "error", err)
+			} else {
+				for _, file := range loadedFiles {
+					ui.Success(fmt.Sprintf("Loaded %s", filepath.Base(file)))
+				}
+				mergedEnv = envpkg.MergeEnvSlices(mergedEnv, envpkg.MapToSlice(dirEnv))
+			}
+		}
+	}
+
 	for _, envVar := range envVars {
 		mergedEnv = envpkg.UpdateEnvVar(mergedEnv, parseEnvVarKey(envVar), parseEnvVarValue(envVar))
 	}
@@ -249,7 +294,7 @@ func execTerraformShellCommand(
 
 	// Merge env vars, ensuring componentEnvList takes precedence.
 	// Include global env from atmos.yaml (lowest priority after system env).
-	mergedEnv := envpkg.MergeSystemEnvWithGlobal(componentEnvList, atmosConfig.Env)
+	mergedEnv := envpkg.MergeSystemEnvWithGlobal(componentEnvList, atmosConfig.GetCaseSensitiveEnvVars())
 
 	// Transfer stdin, stdout, and stderr to the new process and also set the target directory for the shell to start in
 	pa := os.ProcAttr{
@@ -354,7 +399,7 @@ func ExecAuthShellCommand(
 
 	// Merge env vars, ensuring authEnvList takes precedence.
 	// Include global env from atmos.yaml (lowest priority after system env).
-	mergedEnv := envpkg.MergeSystemEnvSimpleWithGlobal(authEnvList, atmosConfig.Env)
+	mergedEnv := envpkg.MergeSystemEnvSimpleWithGlobal(authEnvList, atmosConfig.GetCaseSensitiveEnvVars())
 
 	// Determine shell command and args.
 	shellCommand, shellCommandArgs := determineShell(shellOverride, shellArgs)

internal/exec/shell_utils_test.go

@@ -598,6 +598,7 @@ func TestExecuteShell(t *testing.T) {
 
 	t.Run("simple echo command", func(t *testing.T) {
 		err := ExecuteShell(
+			nil, // no atmosConfig needed for basic tests
 			"echo 'test'",
 			"test-shell",
 			".",
@@ -609,6 +610,7 @@ func TestExecuteShell(t *testing.T) {
 
 	t.Run("dry run mode", func(t *testing.T) {
 		err := ExecuteShell(
+			nil, // no atmosConfig needed for basic tests
 			"echo 'test'",
 			"test-shell",
 			".",
@@ -620,6 +622,7 @@ func TestExecuteShell(t *testing.T) {
 
 	t.Run("syntax error in shell command", func(t *testing.T) {
 		err := ExecuteShell(
+			nil, // no atmosConfig needed for basic tests
 			"echo 'unclosed quote",
 			"test-shell",
 			".",
@@ -631,6 +634,7 @@ func TestExecuteShell(t *testing.T) {
 
 	t.Run("custom environment variables", func(t *testing.T) {
 		err := ExecuteShell(
+			nil, // no atmosConfig needed for basic tests
 			"echo test",
 			"test-shell",
 			".",
@@ -654,6 +658,7 @@ func TestExecuteShell(t *testing.T) {
 		// The shell command should see the override value, not the parent value,
 		// but should still have access to PATH.
 		err := ExecuteShell(
+			nil, // no atmosConfig needed for basic tests
 			"test \"$TEST_OVERRIDE\" = \"custom_value\" && env | grep -q PATH",
 			"test-shell",
 			".",
@@ -677,6 +682,7 @@ func TestExecuteShell(t *testing.T) {
 
 		// Call ExecuteShell with empty env slice, just like workflow commands do.
 		err := ExecuteShell(
+			nil, // no atmosConfig needed for basic tests
 			"env",
 			"test-shell",
 			".",
@@ -711,6 +717,7 @@ func TestExecuteShell(t *testing.T) {
 		for _, tc := range testCases {
 			t.Run(tc.cmd, func(t *testing.T) {
 				err := ExecuteShell(
+					nil, // no atmosConfig needed for basic tests
 					tc.cmd,
 					"test-shell",
 					".",

internal/exec/stack_processor_process_stacks.go

@@ -229,7 +229,7 @@ func ProcessStackConfig(
 	}
 
 	// Include atmos.yaml global env as lowest priority in the merge chain.
-	atmosConfigEnv := envpkg.ConvertMapStringToAny(atmosConfig.Env)
+	atmosConfigEnv := envpkg.ConvertMapStringToAny(atmosConfig.GetCaseSensitiveEnvVars())
 	globalAndTerraformEnv, err := m.Merge(atmosConfig, []map[string]any{atmosConfigEnv, globalEnvSection, terraformEnv})
 	if err != nil {
 		return nil, err

internal/exec/workflow_adapters.go

@@ -31,10 +31,12 @@ func NewWorkflowCommandRunner(_ *schema.RetryConfig) *WorkflowCommandRunner {
 }
 
 // RunShell executes a shell command using ExecuteShell.
+// Note: atmosConfig is nil here because workflows call RunAtmos for atmos commands,
+// and shell commands don't need atmosConfig for basic execution.
 func (r *WorkflowCommandRunner) RunShell(command, name, dir string, env []string, dryRun bool) error {
 	defer perf.Track(nil, "exec.WorkflowCommandRunner.RunShell")()
 
-	return ExecuteShell(command, name, dir, env, dryRun)
+	return ExecuteShell(nil, command, name, dir, env, dryRun)
 }
 
 // RunAtmos executes an atmos command using ExecuteShellCommand.

internal/exec/workflow_utils.go

@@ -323,14 +323,14 @@ func ExecuteWorkflow(
 
 		// Prepare environment variables: start with system env + global env from atmos.yaml.
 		// If identity is specified, also authenticate and add credentials.
-		stepEnv, err := prepareStepEnvironment(stepIdentity, step.Name, authManager, atmosConfig.Env)
+		stepEnv, err := prepareStepEnvironment(stepIdentity, step.Name, authManager, atmosConfig.GetCaseSensitiveEnvVars())
 		if err != nil {
 			return err
 		}
 		switch commandType {
 		case "shell":
 			commandName := fmt.Sprintf("%s-step-%d", workflow, stepIdx)
-			err = ExecuteShell(command, commandName, ".", stepEnv, dryRun)
+			err = ExecuteShell(&atmosConfig, command, commandName, ".", stepEnv, dryRun)
 		case "atmos":
 			args := strings.Fields(command)
 

pkg/config/load.go

@@ -19,9 +19,11 @@ import (
 	errUtils "github.com/cloudposse/atmos/errors"
 	"github.com/cloudposse/atmos/pkg/auth/provisioning"
 	"github.com/cloudposse/atmos/pkg/config/casemap"
+	"github.com/cloudposse/atmos/pkg/env"
 	"github.com/cloudposse/atmos/pkg/filesystem"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/schema"
+	"github.com/cloudposse/atmos/pkg/ui"
 	u "github.com/cloudposse/atmos/pkg/utils"
 	"github.com/cloudposse/atmos/pkg/version"
 	"github.com/cloudposse/atmos/pkg/xdg"
@@ -276,6 +278,11 @@ func LoadConfig(configAndStacksInfo *schema.ConfigAndStacksInfo) (schema.AtmosCo
 	}
 	setEnv(v)
 
+	// Early .env file loading: MUST happen before profile detection.
+	// This allows ATMOS_PROFILE and other ATMOS_* vars in .env files to influence Atmos behavior.
+	// The base path may not be fully resolved yet, so we use what's available from config.
+	loadEnvFilesEarly(v, v.GetString("base_path"))
+
 	// Load profiles if specified via --profile flag or ATMOS_PROFILE env var.
 	// Profiles are loaded after base config but before final unmarshaling.
 	// This allows profiles to override base config settings.
@@ -325,9 +332,11 @@ func LoadConfig(configAndStacksInfo *schema.ConfigAndStacksInfo) (schema.AtmosCo
 	// Both AtmosConfiguration.Env and Command.Env use "env" but with different types
 	// (map[string]string vs []CommandEnv), causing mapstructure to silently drop Commands.
 	// Using mapstructure:"-" on the Env fields and extracting manually here fixes this.
-	if envMap := v.GetStringMapString("env"); len(envMap) > 0 {
-		atmosConfig.Env = envMap
-	}
+	//
+	// The env section supports two forms:
+	// 1. Structured: env.vars (map) + env.files (EnvFilesConfig)
+	// 2. Flat (legacy): env as direct key-value map
+	parseEnvConfig(v, &atmosConfig)
 	if envMap := v.GetStringMapString("templates.settings.env"); len(envMap) > 0 {
 		atmosConfig.Templates.Settings.Env = envMap
 	}
@@ -1231,10 +1240,93 @@ func loadEmbeddedConfig(v *viper.Viper) error {
 	return nil
 }
 
+// parseEnvConfig extracts the env section from Viper, supporting both structured and flat forms.
+// Structured form: env.vars (map) + env.files (EnvFilesConfig)
+// Flat form (legacy): env as direct key-value map.
+func parseEnvConfig(v *viper.Viper, atmosConfig *schema.AtmosConfiguration) {
+	// Check if env section uses structured or flat form.
+	envRaw := v.Get("env")
+	if envRaw == nil {
+		return
+	}
+
+	envMap, ok := envRaw.(map[string]any)
+	if !ok {
+		return
+	}
+
+	// Detect structured form by presence of "vars" or "files" keys.
+	_, hasVars := envMap["vars"]
+	_, hasFiles := envMap["files"]
+
+	if hasVars || hasFiles {
+		// Structured form: env.vars + env.files.
+		if hasVars {
+			atmosConfig.Env.Vars = v.GetStringMapString("env.vars")
+		}
+		// Files config is parsed via mapstructure into atmosConfig.Env.Files.
+		atmosConfig.Env.Files.Enabled = v.GetBool("env.files.enabled")
+		atmosConfig.Env.Files.Paths = v.GetStringSlice("env.files.paths")
+		atmosConfig.Env.Files.Parents = v.GetBool("env.files.parents")
+	} else {
+		// Flat form: all keys are vars (backward compatibility).
+		atmosConfig.Env.Vars = v.GetStringMapString("env")
+	}
+}
+
+// loadEnvFilesEarly loads .env files early in the config loading process.
+// This must happen before profile detection to allow ATMOS_* variables
+// from .env files to influence Atmos behavior.
+// Returns the list of loaded files for UI feedback.
+func loadEnvFilesEarly(v *viper.Viper, basePath string) []string {
+	// Check if env.files is enabled (quick bootstrap read).
+	if !v.GetBool("env.files.enabled") {
+		return nil
+	}
+
+	paths := v.GetStringSlice("env.files.paths")
+	if len(paths) == 0 {
+		paths = []string{".env"} // Default pattern.
+	}
+
+	// Determine base path for loading.
+	if basePath == "" {
+		basePath = v.GetString("base_path")
+	}
+	if basePath == "" {
+		basePath = "."
+	}
+
+	// Load .env files from base path.
+	envVars, loadedFiles, err := env.LoadEnvFiles(basePath, paths)
+	if err != nil {
+		log.Debug("Failed to load .env files", "error", err)
+		return nil
+	}
+
+	// Inject into process environment (don't override existing).
+	// This allows ATMOS_* vars to influence Atmos behavior.
+	for k, val := range envVars {
+		if _, exists := os.LookupEnv(k); !exists {
+			if err := os.Setenv(k, val); err != nil { //nolint:forbidigo // Intentional: setting env vars from .env files
+				log.Debug("Failed to set env var from .env file", "key", k, "error", err)
+			}
+		}
+	}
+
+	// Report loaded files via UI.
+	for _, file := range loadedFiles {
+		ui.Success(fmt.Sprintf("Loaded %s", filepath.Base(file)))
+	}
+
+	return loadedFiles
+}
+
 // caseSensitivePaths lists the YAML paths that need case preservation.
 // Viper lowercases all map keys, but these sections need original case.
 var caseSensitivePaths = []string{
-	"env",             // Environment variables (e.g., GITHUB_TOKEN)
+	"env",             // Environment variables (e.g., GITHUB_TOKEN) - flat form
+	"env.vars",        // Environment variables - structured form
 	"auth.identities", // Auth identity names (e.g., SuperAdmin)
 }