Skip to main content

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:

VariableDescriptionExample
{{.Component}}The Atmos component namevpc, eks, database
{{.Stack}}The Atmos stack nametenant1-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
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.

atmos terraform shell <component> -s <stack> --identity dev-role
--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
--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.

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

atmos terraform shell <component> -s <stack> --skip-init