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.

atmos terraform shell --help

Usage

Execute the terraform shell command like this:

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)

• 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:

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:

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

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

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

Arguments

component (required)

Atmos terraform component.

Flags

--stack (alias -s) (required)

Atmos stack.

--dry-run (optional)

Dry run.

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.

atmos terraform shell <component> -s <stack> --process-templates=false

--process-functions (optional)

Enable/disable YAML functions processing in Atmos stack manifests
when executing terraform commands.

If the flag is not passed, YAML function processing is enabled by default.

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.

atmos terraform shell <component> -s <stack> --skip=eval --skip=include
atmos terraform shell <component> -s <stack> --skip=terraform.output,include