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

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