# 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 <component> -s <stack>
```

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

    # Run 'terraform init -reconfigure' when entering shell
    init_run_reconfigure: true

    # 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_RUN_RECONFIGURE=true
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 <component> -s <stack> --identity dev-role
  ```
- **`--dry-run` (optional)**

  Dry run.
  ```shell
  atmos terraform shell <component> -s <stack> --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 <component> -s <stack> --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 <component> -s <stack> --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 <component> -s <stack> --skip=eval --skip=include
  atmos terraform shell <component> -s <stack> --skip=terraform.output,include
  ```
- **`--with-secrets` (optional)**

  Export the component's secret-bearing variables into the interactive shell as
  `TF_VAR_<name>` 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 <component> -s <stack> --with-secrets
  ```
- **`--skip-init` (optional)**

  Skip running `terraform init` before launching the shell. By default Atmos runs
  `terraform init` (and selects/creates the workspace) so you enter an initialized
  component, matching the behavior described above. Use this to enter the shell faster
  when the component is already initialized.

  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 <component> -s <stack> --skip-init
  ```

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