atmos terraform
Use these subcommands to interact with Terraform and OpenTofu.
Atmos supports all Terraform and OpenTofu commands and options described in Terraform CLI Overview and OpenTofu Basic CLI Features.
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.
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:
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
--stackflag - Component must exist in the specified stack configuration
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.
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 initbefore executing other commands. Use--skip-initto skip this step. -
Deploy command:
atmos terraform deployexecutesterraform apply -auto-approvefor automated deployments. -
Planfile support: The
--from-planand--planfileflags enable two-stage plan/apply workflows. See Terraform Planfiles. -
Terraform Cloud compatibility: Use
--skip-planfilewithterraform planwhen 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
Run atmos terraform --help to see all available options.
Examples
Component Name Examples
Path-Based Examples
Clean Examples
Workspace Examples
Additional Flag Examples
Arguments
component(required for Single-Component commands)Atmos Terraform/OpenTofu component name or filesystem path.
Supports both:- Component names:
vpc,infra/vpc,test/test-component - Filesystem paths:
.(current directory),./vpc,components/terraform/vpc
When using paths, Atmos automatically resolves the path to the component name based on your stack configuration. See Path-Based Component Resolution above.
- Component names:
Flags
--stack(alias-s) (required for Single-Component commands)Atmos stack.
atmos terraform plan <component> --stack <stack>
atmos terraform apply --all -s <stack>--dry-run(optional)Dry run. Simulate the command without making any changes.
atmos terraform <command> <component> -s <stack> --dry-run
atmos terraform <command> --all --dry-run
atmos terraform <command> --affected --dry-run--redirect-stderr(optional)File descriptor to redirect
stderrto.Errors can be redirected to any file or any standard file descriptor (including
/dev/null).--append-user-agent(optional)Append a custom User-Agent to Terraform requests.
Can also be set using the
ATMOS_COMPONENTS_TERRAFORM_APPEND_USER_AGENTenvironment variable.--skip-init(optional)Skip running
terraform initbefore executing terraform commands.atmos terraform apply <component> -s <stack> --skip-init--skip-planfile(optional)Skip writing the plan to a file. If the flag is set to
true, Atmos will not pass the-outflag to Terraform when executingterraform plancommands. Set it totruewhen using Terraform Cloud since the-outflag is not supported. Terraform Cloud automatically stores plans in its backend and can't store it in a local fileatmos terraform plan <component> -s <stack> --skip-planfile=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 plan <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 plan <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
--skipflags, or separate the functions with a comma.atmos terraform plan <component> -s <stack> --skip=eval --skip=include
atmos terraform apply <component> -s <stack> --skip=terraform.output,include--components(optional)Execute the command on the specified components in all stacks or in a specific stack.
atmos terraform plan --components <component-1>
atmos terraform plan --components <component-1>,<component-2>
atmos terraform apply --components <component-1> --components <component-2>
atmos terraform apply --components <component-1>,<component-2> --stack <stack> --logs-level=Debug--all(optional)Execute the command on all components in all stacks or in a specific stack.
atmos terraform plan --all
atmos terraform apply --all --stack <stack>
atmos terraform apply --all --dry-run
atmos terraform deploy --all --logs-level=Debug--query(optional)Execute the command on the components filtered by a YQ expression, in all stacks or in a specific stack.
NOTE: All Atmos sections are available in the expression, e.g.
vars,locals,settings,env,metadata,backend, etc.atmos terraform plan --query '.vars.tags.team == "data"'
atmos terraform apply --query '.vars.tags.team == "eks"' --stack <stack>
atmos terraform apply --query '.settings.context.account_id == 12345'
atmos terraform deploy --query '.vars.tags.team == "data"' --dry-run --logs-level=Debug--affected(optional)Execute the command on all the directly affected components, in all stacks or in a specific stack, in dependency order (if component dependencies are configured).
NOTE: When using the
--affectedflag, Atmos supports all the flags from theatmos describe affectedCLI command.atmos terraform plan --affected
atmos terraform apply --affected --stack <stack>
atmos terraform apply --affected --dry-run
atmos terraform apply --affected --clone-target-ref=true
atmos terraform deploy --affected --include-dependents
atmos terraform apply --affected --include-dependents --dry-run --logs-level=Debug--include-dependents(optional; can only be used in conjunction with the--affectedflag)For each directly affected component, detect the dependent components and process them in dependency order, recursively. Dependents are components that are indirectly affected, meaning that nothing in the current branch modifies their code or configs, but they are configured as dependencies of the components that are modified.
atmos terraform plan --affected --include-dependents --logs-level=Debug
atmos terraform apply --affected --include-dependents --dry-run
atmos terraform apply --affected --include-dependents --stack prod --dry-run--ref(optional; can only be used in conjunction with the--affectedflag)Git Reference with which to compare the current working branch.
If the reference is a branch, the command will compare the current working branch with the branch.
If the reference is a tag, the command will compare the current working branch with the tag.
If the flags are not provided, the ref will be set automatically to the head to the default branch (
refs/remotes/origin/HEADGit ref, usually themainbranch)--sha(optional; can only be used in conjunction with the--affectedflag)Git commit SHA with which to compare the current working branch
--ssh-key(optional; can only be used in conjunction with the--affectedflag)Path to PEM-encoded private key to clone private repos using SSH
--ssh-key-password(optional; can only be used in conjunction with the--affectedflag)Encryption password for the PEM-encoded private key if the key contains a password-encrypted PEM block
--repo-path(optional; can only be used in conjunction with the--affectedflag)Path to the already cloned target repository with which to compare the current branch. Conflicts with
--ref,--sha,--ssh-keyand--ssh-key-password--clone-target-ref(optional; can only be used in conjunction with the--affectedflag)Clone the target reference with which to compare the current branch.
atmos terraform plan --affected --clone-target-ref=true
atmos terraform deploy --affected --clone-target-ref=true --dry-run
atmos terraform apply --affected --clone-target-ref=true --dry-run --logs-level=DebugIf the flag is not passed or set to
false(default), the target reference will be checked out instead. This requires that the target reference is already cloned by Git, and the information about it exists in the.gitdirectory--identity(alias-i) (optional)Specify the identity to authenticate before running Terraform commands. This flag has four modes:
- With identity name (
--identity adminor--identity=admin): Use the specified identity - Without value (
--identity): Show interactive selector to choose identity - With
false(--identity=false): Disable Atmos authentication and use AWS SDK defaults - Omitted: Use the default identity configured in
atmos.yaml, or prompt if no default is set
# Use specific identity (equals syntax recommended)
atmos terraform plan <component> -s <stack> --identity=admin
# Use specific identity (space syntax)
atmos terraform plan <component> -s <stack> --identity admin
# Interactively select identity
atmos terraform apply <component> -s <stack> --identity
# Disable authentication (use AWS SDK defaults)
atmos terraform plan <component> -s <stack> --identity=false
# Use default identity (or prompt if none configured)
atmos terraform plan <component> -s <stack>Flag Placement Best PracticeWhen using
--identitywith a value, place it after the stack flag and before the--separator (if passing Terraform-native flags):# Recommended: --identity before -- separator
atmos terraform plan <component> -s <stack> --identity=admin -- -var-file=extra.tfvars
# The equals syntax (--identity=admin) is unambiguous and works in all contextsWhen set to
false(or0,no,off), Atmos skips identity authentication entirely and uses standard cloud provider SDK credential resolution (e.g., environment variables, shared credentials file, instance metadata, OIDC). This is useful in CI/CD environments using external authentication mechanisms.See Disabling Authentication for more details.
Environment variables:
ATMOS_IDENTITYorIDENTITY(checked in that order)- With identity name (
All native Terraform/OpenTofu flags are supported.
Multi-Component Commands (Bulk Operations) Examples
Let's assume that we have the following Atmos stack manifests in the prod and nonprod stacks,
with dependencies between the components:
Let's run the following Multi-Component commands in dry-run mode and review the output to understand what each command executes:
Learn how to configure Terraform components in your atmos.yaml, including backends, workspaces, and provider generation.
Subcommands
Use this command to apply Terraform changes for an Atmos component in a stack. Supports both direct applies and applying from previously generated planfiles.
Manage Terraform state backend infrastructure
Clean up Terraform files for an Atmos component in a stack
Use this command to open an interactive Terraform console for an Atmos component in a stack, with all component variables and configuration pre-loaded.
Use this command to deploy Terraform changes for an Atmos component in a stack with auto-approval. This combines plan and apply operations in a single command.
Use this command to destroy Terraform-managed infrastructure for an Atmos component in a stack. This operation removes all resources managed by the component.
Use this command to format Terraform HCL configuration files for an Atmos component to canonical format and style.
Use this command to manually unlock the Terraform state for an Atmos component in a stack when automatic unlocking fails.
6 items
Use this command to download and update Terraform modules for an Atmos component. This ensures all module dependencies are available locally.
Use this command to generate a visual dependency graph for an Atmos component's Terraform resources in a specific stack.
Use this command to import existing infrastructure resources into the Terraform state for an Atmos component in a stack.
Use this command to initialize the Terraform working directory for an Atmos component in a stack. This prepares the component for other Terraform operations.
Use this command to authenticate with Terraform Cloud or Terraform Enterprise for an Atmos component in a stack.
Use this command to remove Terraform Cloud or Terraform Enterprise credentials for an Atmos component in a stack.
Use this command to retrieve Terraform metadata functions for an Atmos component in a stack.
Use this command to list all Terraform modules used by an Atmos component in a stack.
Read Terraform output values for an Atmos component from the state file
Use this command to generate a Terraform execution plan for an Atmos component in a stack, showing what changes would be made to your infrastructure.
The atmos terraform plan-diff command compares two Terraform plans and shows the differences between them.
5 items
3 items
Use this command to display provider requirements and configurations for an Atmos component's Terraform configuration in a stack.
Use this command to refresh the Terraform state for an Atmos component in a stack, updating it to match the current remote infrastructure.
This command starts a new `SHELL` configured with the environment for an Atmos component in a stack to allow execution of all native terraform commands inside the shell without using any atmos-specific arguments and flags. This may by helpful to debug a component without going through Atmos.
Use this command to display human-readable output from the Terraform state or planfile for an Atmos component in a stack.
4 items
7 items
Use this command to manage the Terraform state for an Atmos component in a stack. Supports operations like list, move, pull, push, replace-provider, rm, and show.
Use this command to mark a Terraform resource for recreation in an Atmos component's next apply operation. Note: This command is deprecated in Terraform v1.0+.
Use this command to run Terraform tests for an Atmos component, validating the component's configuration and behavior.
Use this command to remove the tainted state from a Terraform resource in an Atmos component. Note: This command is deprecated in Terraform v1.0+.
Use this command to validate the Terraform HCL configuration files (.tf files) for an Atmos component in a stack, checking for syntax and consistency errors. This validates Terraform code, not Atmos stack YAML configurations.
Use this command to display the Terraform/OpenTofu version being used for an Atmos component in a stack.
4 items
This command calculates the `terraform` workspace for an Atmos component (from the context variables and stack config). It runs `terraform init -reconfigure` and selects the workspace by executing the `terraform workspace select` command.
5 items