Skip to main content

atmos terraform

Use these subcommands to interact with Terraform and OpenTofu.

atmos terraform --help

Atmos supports all Terraform and OpenTofu commands and options described in Terraform CLI Overview and OpenTofu Basic CLI Features.

Disambiguation

The term "Terraform" is used in this documentation to refer to generic concepts such as providers, modules, stacks, the HCL-based domain-specific language and its interpreter. Atmos works with OpenTofu.

Command Modes​

Atmos Terraform commands operate in two modes:

  • Single-Component: Execute Terraform for one component at a time with precise control
  • Multi-Component: Execute Terraform across multiple components using filters (--all, --affected, --components, --query)

Single-Component Usage​

Use single-component commands when you want to execute Terraform operations on one component at a time.

atmos terraform <command> <component> -s <stack> [options]

The component argument and --stack flag are required to generate variables and backend config for the component in the stack.

See individual command pages for detailed options: plan, apply, deploy, destroy.

Path-Based Component Resolution​

Atmos supports using filesystem paths instead of component names for convenience. This allows you to navigate to a component directory and use . to reference it:

# Navigate to component directory
cd components/terraform/vpc

# Use . to reference current directory
atmos terraform plan . -s dev
atmos terraform apply . -s dev

This automatically resolves the path to the component name configured in your stack, eliminating the need to remember exact component names.

Supported path formats:

  • . - Current directory
  • ./component - Relative path from current directory
  • ../other-component - Relative path to sibling directory
  • /absolute/path/to/component - Absolute path

Requirements:

  • Must be inside a component directory under the configured base path
  • Must specify --stack flag
  • Component must exist in the specified stack configuration
Interactive Component Selection

When a component path matches multiple components in the stack, Atmos prompts you to select which one to use in interactive terminals.

For example, if both station/1 and station/2 reference components/terraform/weather:

cd components/terraform/weather
atmos terraform plan . --stack dev
# Atmos displays: "Component path '.' matches multiple instances in stack 'dev'"
# Select which component instance to use: station/1, station/2

In non-interactive mode (CI/CD), use the explicit component name to avoid ambiguity:

atmos terraform plan station/1 --stack dev  # Explicit and unambiguous
atmos terraform plan station/2 --stack dev  # Explicit and unambiguous

Multi-Component Usage​

Use multi-component commands to run Terraform operations across multiple components simultaneously. You can target components by stack, selector, query, or change detection.

# Execute on all components in all stacks
atmos terraform <command> --all

# Execute on all components in a specific stack
atmos terraform <command> --stack prod

# Execute on specific components
atmos terraform <command> --components vpc,eks

# Execute on affected components (based on git changes)
atmos terraform <command> --affected

# Execute on components matching a query
atmos terraform <command> --query '.vars.tags.team == "eks"'

All multi-component flags can be combined with --dry-run to preview what would be executed without making changes.

See individual command pages for detailed multi-component examples and flags: plan, apply, deploy.

Differences from Native Terraform​

Atmos enhances the standard Terraform CLI with several conveniences:

  • Automatic initialization: Atmos runs terraform init before executing other commands. Use --skip-init to skip this step.

  • Deploy command: atmos terraform deploy executes terraform apply -auto-approve for automated deployments.

  • Planfile support: The --from-plan and --planfile flags enable two-stage plan/apply workflows. See Terraform Planfiles.

  • Terraform Cloud compatibility: Use --skip-planfile with terraform plan when using Terraform Cloud, which doesn't support local plan files.

  • Native flag passthrough: Use -- to pass flags directly to Terraform:

    atmos terraform plan vpc -s dev -- -refresh=false
    atmos terraform apply vpc -s dev -- -lock=false
tip

Run atmos terraform --help to see all available options.

Configure Terraform

Learn how to configure Terraform components in your atmos.yaml, including backends, workspaces, and provider generation.

Learn More

Subcommands​