# atmos terraform shell This command starts a new `SHELL` configured with the environment for an Atmos component in a Stack to allow executing all native terraform commands inside the shell without using any atmos-specific arguments and flags. ## Usage Execute the `terraform shell` command like this: ```shell atmos terraform shell -s ``` The command configures the environment for an Atmos component in a stack and starts a new shell suitable for executing all terraform commands natively without going through Atmos. The command does the following: - Processes the stack manifests, generates the required variables for the Atmos component in the stack, and writes them to a file in the component's folder - Generates a backend config file for the Atmos component in the stack and writes it to a file in the component's folder (or as specified by the [Atmos configuration setting](/cli/configuration)) - Creates a `terraform` workspace for the component in the stack - Drops the user into a separate shell (process) with all the required paths and ENV vars set - Inside the shell, the user can execute all `terraform` commands using the native syntax - Atmos sets the `ATMOS_SHLVL` environment variable to track the nesting level of shells: - If `ATMOS_SHLVL` is not already set, Atmos initializes it to `1`. - If `ATMOS_SHLVL` is already set, Atmos increments its value by `1` for each new nested shell. :::tip Run `atmos terraform shell --help` to see all the available options ::: ## Configuration Configure shell behavior in your `atmos.yaml`: ```yaml components: terraform: # Auto-generate backend configuration auto_generate_backend_file: true # Init behavior when entering shell (auto skips init/-reconfigure when unneeded) init: mode: auto reconfigure: auto # Enable workspace management workspaces_enabled: true # Customize the shell prompt using Go template syntax shell: prompt: "atmos [{{.Stack}}] {{.Component}} $ " ``` ### Shell Prompt Customization The `shell.prompt` configuration supports Go template syntax with the following variables: | Variable | Description | Example | |----------|-------------|---------| | `{{.Component}}` | The Atmos component name | `vpc`, `eks`, `database` | | `{{.Stack}}` | The Atmos stack name | `tenant1-ue2-dev`, `prod-us-west-2` | Shell-native format specifiers are preserved and will be expanded by your shell: - **Bash**: Escape sequences like `\u` (username), `\h` (hostname), `\w` (working directory), `\[` `\]` (color codes) - **Zsh**: Percent sequences like `%n` (username), `%m` (hostname), `%~` (directory), `%F{color}` (colors) **Example prompts:** ```yaml # Basic: Show stack and component shell: prompt: "atmos [{{.Stack}}] {{.Component}} $ " # Output: atmos [tenant1-ue2-dev] vpc $ # Bash: With username and hostname shell: prompt: '\u@\h [{{.Stack}}] {{.Component}} $ ' # Output: erik@macbook [tenant1-ue2-dev] vpc $ # Bash: With colors shell: prompt: '\[\e[1;32m\]\u@\h\[\e[0m\]:\[\e[1;34m\]{{.Stack}}\[\e[0m\] [{{.Component}}] \$ ' # Output: (colored) erik@macbook:tenant1-ue2-dev [vpc] $ # Zsh: With username and colors shell: prompt: '%F{cyan}%n@%m%f:%F{blue}{{.Stack}}%f [{{.Component}}] %# ' # Output: (colored) erik@macbook:tenant1-ue2-dev [vpc] % # Minimal shell: prompt: "[{{.Component}}] $ " # Output: [vpc] $ # Emoji shell: prompt: "🚀 {{.Component}} @ {{.Stack}} $ " # Output: 🚀 vpc @ tenant1-ue2-dev $ ``` These settings can also be controlled via environment variables: ```shell export ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE=true export ATMOS_COMPONENTS_TERRAFORM_INIT_MODE=auto export ATMOS_COMPONENTS_TERRAFORM_INIT_RECONFIGURE=auto export ATMOS_COMPONENTS_TERRAFORM_INIT_UPGRADE=auto export ATMOS_COMPONENTS_TERRAFORM_WORKSPACES_ENABLED=true ``` ## Examples ```shell atmos terraform shell top-level-component1 -s tenant1-ue2-dev atmos terraform shell infra/vpc -s tenant1-ue2-staging atmos terraform shell test/test-component-override-3 -s tenant2-ue2-prod atmos terraform shell infra/vpc -s tenant1-ue2-dev --identity dev-role ``` ## Arguments - **`component` (required)** Atmos terraform component. ## Flags - **`--stack` (alias `-s`) (required)** Atmos stack. - **`--identity` (alias `-i`) (optional)** Identity to use for authentication. Overrides the component's default identity. ```shell atmos terraform shell -s --identity dev-role ``` - **`--dry-run` (optional)** Dry run. ```shell atmos terraform shell -s --dry-run=true ``` - **`--process-templates` (optional)** Enable/disable Go template processing in Atmos stack manifests when executing terraform commands. If the flag is not passed, template processing is enabled by default. ```shell atmos terraform shell -s --process-templates=false ``` - **`--process-functions` (optional)** Enable/disable YAML functions processing in Atmos stack manifestswhen executing terraform commands. If the flag is not passed, YAML function processing is enabled by default. ```shell atmos terraform shell -s --process-functions=false ``` - **`--skip` (optional)** Skip processing a specific Atmos YAML function in Atmos stacks manifests when executing terraform commands. To specify more than one function, use multiple `--skip` flags, or separate the functions with a comma. ```shell atmos terraform shell -s --skip=eval --skip=include atmos terraform shell -s --skip=terraform.output,include ``` - **`--with-secrets` (optional)** Export the component's secret-bearing variables into the interactive shell as `TF_VAR_` environment variables. **Disabled by default** so secrets are not exposed in the shell environment. Resolved secrets are never written to the on-disk varfile. By default they are also withheld from the shell, so `terraform` commands run inside the shell will not see them (variables that require a secret will prompt or fail). Pass `--with-secrets` when you need those commands to work with the real values. Can also be set via the `ATMOS_WITH_SECRETS` environment variable. ```shell atmos terraform shell -s --with-secrets ``` - **`--skip-init` (optional)** Skip running `terraform init` before launching the shell. By default Atmos ensures the component is initialized (and selects/creates the workspace) so you enter an initialized component, matching the behavior described above — with `init.mode: auto` (the default), it may skip actually running `terraform init` when nothing relevant has changed. Use this flag to skip that check entirely and enter the shell faster. Workspace selection is unaffected by this flag — it stays governed by the [`workspaces_enabled`](/cli/configuration/components/terraform) setting. For a shell that neither initializes nor switches workspaces, combine `--skip-init` with `workspaces_enabled: false`. Can also be set via the `ATMOS_SKIP_INIT` environment variable. ```shell atmos terraform shell -s --skip-init ``` - **`--init-mode` (optional)** Override [`init.mode`](/cli/configuration/components/terraform#configuration-reference) for this invocation: `auto` (default), `always`, or `never` (disables the ordinary implicit init, but unlike `--skip-init` does not suppress the forced reconfigure init that `atmos terraform workspace select`/`new` needs). ```shell atmos terraform shell -s --init-mode=always ``` - **`--init-reconfigure` (optional)** Override [`init.reconfigure`](/cli/configuration/components/terraform#configuration-reference) for this invocation: `auto` (default), `always`, or `never`. ```shell atmos terraform shell -s --init-reconfigure=always ``` - **`--init-upgrade` (optional)** Override [`init.upgrade`](/cli/configuration/components/terraform#configuration-reference) for this invocation: `auto` (default), `always`, or `never`. ```shell atmos terraform shell -s --init-upgrade=always ``` ## Related Commands - [terraform plan](/cli/commands/terraform/plan) - Generate an execution plan - [terraform apply](/cli/commands/terraform/apply) - Apply changes to infrastructure - [terraform init](/cli/commands/terraform/init) - Initialize a Terraform working directory