Export configuration information in shell launched by Atmos (#827)

internal/exec/shell_utils.go

@@ -185,13 +185,20 @@ func execTerraformShellCommand(
 		}
 	}()
 
+	// Set the Terraform environment variables to reference the var file
 	componentEnvList = append(componentEnvList, fmt.Sprintf("TF_CLI_ARGS_plan=-var-file=%s", varFile))
 	componentEnvList = append(componentEnvList, fmt.Sprintf("TF_CLI_ARGS_apply=-var-file=%s", varFile))
 	componentEnvList = append(componentEnvList, fmt.Sprintf("TF_CLI_ARGS_refresh=-var-file=%s", varFile))
 	componentEnvList = append(componentEnvList, fmt.Sprintf("TF_CLI_ARGS_import=-var-file=%s", varFile))
 	componentEnvList = append(componentEnvList, fmt.Sprintf("TF_CLI_ARGS_destroy=-var-file=%s", varFile))
 	componentEnvList = append(componentEnvList, fmt.Sprintf("TF_CLI_ARGS_console=-var-file=%s", varFile))
 
+	// Set environment variables to indicate the details of the Atmos shell configuration
+	componentEnvList = append(componentEnvList, fmt.Sprintf("ATMOS_STACK=%s", stack))
+	componentEnvList = append(componentEnvList, fmt.Sprintf("ATMOS_COMPONENT=%s", component))
+	componentEnvList = append(componentEnvList, fmt.Sprintf("ATMOS_SHELL_WORKING_DIR=%s", workingDir))
+	componentEnvList = append(componentEnvList, fmt.Sprintf("ATMOS_TERRAFORM_WORKSPACE=%s", workspaceName))
+
 	hasCustomShellPrompt := cliConfig.Components.Terraform.Shell.Prompt != ""
 	if hasCustomShellPrompt {
 		// Template for the custom shell prompt
@@ -255,6 +262,9 @@ func execTerraformShellCommand(
 
 		shellName := filepath.Base(shellCommand)
 
+		// This means you cannot have a custom shell prompt inside Geodesic (Geodesic requires "-l").
+		// Perhaps we should have special detection for Geodesic?
+		// We could test if env var GEODESIC_SHELL is set to "true" (or set at all).
 		if !hasCustomShellPrompt {
 			shellCommand = shellCommand + " -l"
 		}

website/docs/cli/configuration/configuration.mdx

@@ -599,6 +599,7 @@ functions.
 
 
 ## Environment Variables
+### Configuration
 
 Most YAML settings can also be defined by environment variables. This is helpful while doing local development. For example,
 setting `ATMOS_STACKS_BASE_PATH` to a path in `/localhost` to your local development folder, will enable you to rapidly iterate.
@@ -632,3 +633,21 @@ setting `ATMOS_STACKS_BASE_PATH` to a path in `/localhost` to your local develop
 | ATMOS_LOGS_FILE                                       | logs.file                                       | The file to write Atmos logs to. Logs can be written to any file or any standard file descriptor, including `/dev/stdout`, `/dev/stderr` and `/dev/null`). If omitted, `/dev/stdout` will be used                            |
 | ATMOS_LOGS_LEVEL                                      | logs.level                                      | Logs level. Supported log levels are `Trace`, `Debug`, `Info`, `Warning`, `Off`. If the log level is set to `Off`, Atmos will not log any messages (note that this does not prevent other tools like Terraform from logging) |
 | ATMOS_SETTINGS_LIST_MERGE_STRATEGY                    | settings.list_merge_strategy                    | Specifies how lists are merged in Atmos stack manifests. The following strategies are supported: `replace`, `append`, `merge`                                                                                                |
+
+### Context
+
+Some commands, like [`atmos terraform shell`](/cli/commands/terraform/shell),
+spawn an interactive shell with certain environment variables set, in order to enable the user to use other tools
+(in the case of `atmos terraform shell`, the Terraform or Tofu CLI) natively, while still being configured for a 
+specific component and stack. To accomplish this, and to provide visibility and context to the user regarding the 
+configuration, Atmos may set the following environment variables in the spawned shell:
+
+| Variable                | Description                                                                                            |
+|:------------------------|:-------------------------------------------------------------------------------------------------------|
+| ATMOS_COMPONENT         | The name of the active component                                                                       |
+| ATMOS_SHELL_WORKING_DIR | The directory from which native commands should be run                                                 |
+| ATMOS_SHLVL | The depth of Atmos shell nesting. When present, it indicates that the shell has been spawned by Atmos. |
+| ATMOS_STACK             | The name of the active stack                                                                           |
+| ATMOS_TERRAFORM_WORKSPACE | The name of the Terraform workspace in which Terraform comamnds should be run                          |
+| PS1                     | When a custom shell prompt has been configured in Atmos, the prompt will be set via `PS1`              |
+| TF_CLI_ARGS_*           | Terraform CLI arguments to be passed to Terraform commands                                             |

website/docs/quick-start/install-atmos.mdx

@@ -309,7 +309,7 @@ includes the necessary glyphs and then configure your terminal.
 
 Go to https://www.nerdfonts.com/ for more information.
 
-::tip
+:::tip
 We recommend the "Fira Code" NerdFont version, which is what all our screenshots are based on.
 :::