Atmos Terraform Commands Reference

Complete reference of all atmos terraform subcommands with syntax and key flags.

Command Syntax

atmos terraform <subcommand> <component> -s <stack> [flags] [-- native-terraform-flags]

The component argument and --stack / -s flag are required for most component operations. Source management commands (source pull, source describe, source delete) take a component but do not require --stack. Use -- to pass flags directly to Terraform without Atmos interpretation.

Path-Based Component Resolution

You can use filesystem paths instead of component names:

cd components/terraform/vpc
atmos terraform plan . -s dev
atmos terraform apply . -s dev

Supported path formats: ., ./component, ../sibling, /absolute/path. If a path matches multiple components, Atmos prompts for selection in interactive mode.

Streaming UI (--ui)

plan, apply, deploy, init, and destroy support a --ui flag that renders a live, Docker-build-style progress view (spinners, a dependency tree, per-resource status) instead of raw Terraform output:

atmos terraform apply vpc -s dev --ui

Enable it by default via components.terraform.ui.enabled: true in atmos.yaml or ATMOS_TERRAFORM_UI=true; pass --ui=false to override a config-enabled default for one run. The UI auto-disables when output is piped, in CI (CI=true), or on unsupported commands. refresh doesn't support it — Terraform's refresh doesn't emit the structured -json output the UI depends on; --ui refresh prints a warning and falls back to standard output.

Experimental Saved-Plan Policies

ATMOS_POLICY_DIR opts Terraform execution into strict inline CEL terraform.plan denial rules from explicit atmos/v1, kind: Policy documents. This is not an atmos.yaml setting or a component attachment. The gate checks complete native show -json plan data after planning and again before applying a private copy of the same saved binary. It requires compatible format-1.x plan JSON; do not infer support for remote-only or encrypted plan modes without checking the binary.

When the directory is configured, recommend plan then apply --from-plan or apply --planfile. Apply/deploy must use a saved artifact; implicit apply/deploy, direct destroy, and skipped planfiles fail closed. For destruction, use plan -destroy then saved-plan apply. These checks run without requiring --affected. Dry-run does not evaluate a plan and must not be described as policy approval.

Do not suggest unsetting the directory to bypass a governing policy. Protect the directory, workflow, binaries and environment; local configuration alone is not a tamper-resistant boundary. For policy-selected hooks, GitHub event context, samples/tests and capability limits, use atmos-policy. Attachments, Starlark and approvals remain proposed; legacy validation is unchanged. See https://atmos.tools/cli/commands/terraform/plan-policies for the exact manifest and limits.

Core Lifecycle Commands

init

Initialize the Terraform working directory for a component in a stack.

atmos terraform init <component> -s <stack> [flags]

Atmos enhancements: cleans .terraform/environment; runs automatically before plan/apply/deploy/shell/destroy only when needed (init.mode: auto skips it when nothing relevant changed since the last init); adds -reconfigure/-upgrade only when required (init.reconfigure, auto by default; init.upgrade, never by default since Atmos never passed -upgrade automatically before this setting existed); supports --init-pass-vars for OpenTofu. init_run_reconfigure is deprecated in favor of init.reconfigure.

Key flags:

• --skip-init -- Disables auto-init entirely for this invocation (same as --init-mode=never)
• --init-mode -- Override init.mode for this invocation: auto (default), always, never
• --init-reconfigure -- Override init.reconfigure for this invocation: auto (default), always, never
• --init-upgrade -- Override init.upgrade for this invocation: never (default), auto, always
• --init-pass-vars -- Pass generated varfile to init (OpenTofu feature)
• Native: -reconfigure, -upgrade, -migrate-state, -backend=false, -backend-config=PATH, -force-copy, -get=false, -input=false, -lock=false, -lock-timeout=DURATION, -plugin-dir=PATH

If a skipped init turns out to have been necessary, Atmos recognizes the resulting Terraform/OpenTofu diagnostic (e.g. "Backend initialization required") before any state is touched, re-runs init, and retries the command once. No -migrate-state is ever run implicitly.

plan

Generate a Terraform execution plan.

atmos terraform plan <component> -s <stack> [flags]

Default behavior saves a planfile as <context>-<component>.planfile in the component directory.

Key flags:

• --skip-planfile -- Do not save the plan to a file
• --skip-init -- Skip automatic terraform init
• --dry-run -- Preview without executing
• --process-templates -- Enable/disable Go template processing (default: true)
• --all -- Plan all components in all stacks
• --affected -- Plan only git-affected components
• --components -- Plan specific named components (comma-separated)
• --query -- Filter components by YQ expression
• --include-dependents -- With --affected, include dependent components
• --stack -- Filter multi-component operations to a specific stack
• --ref -- Git reference to compare against (default: refs/remotes/origin/HEAD)
• --sha -- Git commit SHA to compare against
• --clone-target-ref -- Clone target reference instead of checking out
• Native: -out=FILE, -destroy, -target=RESOURCE, -var 'NAME=VALUE', -refresh-only, -refresh=false

apply

Apply Terraform changes for a component in a stack.

atmos terraform apply <component> -s <stack> [flags]

Key flags:

• --from-plan -- Apply the planfile previously generated by atmos terraform plan
• --planfile -- Apply a specific planfile at the given path
• --skip-init -- Skip automatic terraform init
• --dry-run -- Preview without executing
• --all, --affected, --components, --query -- Multi-component operation flags
• --include-dependents, --ref, --sha, --clone-target-ref -- Affected-mode flags
• Native: -auto-approve, -target=RESOURCE, -var 'NAME=VALUE', -refresh-only, -replace=RESOURCE, -parallelism=N

deploy

Plan and apply with auto-approval in a single command.

atmos terraform deploy <component> -s <stack> [flags]

Automatically sets -auto-approve. Designed for CI/CD pipelines.

Key flags:

• --deploy-run-init -- Enable/disable running terraform init before deploy
• --from-plan -- Use previously generated planfile
• --planfile -- Path to a specific planfile
• --dry-run -- Preview without executing
• --process-templates -- Enable/disable Go template processing (default: true)
• --process-functions -- Enable/disable YAML function processing (default: true)
• --skip -- Skip specific YAML functions (comma-separated or repeated)
• --all, --affected, --components, --query -- Multi-component operation flags
• --include-dependents, --ref, --sha, --clone-target-ref -- Affected-mode flags

destroy

Destroy all resources managed by a component in a stack.

atmos terraform destroy <component> -s <stack> [flags]

Key flags:

• --skip-init -- Skip automatic terraform init
• --dry-run -- Preview without executing
• Native: -auto-approve, -target=RESOURCE, -parallelism=N

State and Workspace Commands

workspace

Calculate and select the Terraform workspace for a component in a stack.

atmos terraform workspace <component> -s <stack> [flags]

Runs terraform init -reconfigure, then selects or creates the workspace.

Key flags:

• --dry-run, --process-templates, --process-functions, --skip

state

Manage Terraform state for a component in a stack.

atmos terraform state <subcommand> <component> -s <stack> [args]

Subcommands: list, show, mv, rm, pull, push, replace-provider. Blocks modifications if the component is locked (metadata.locked: true).

Key flags:

• --skip-init, --dry-run

Generation Commands

generate varfile

Generate a .tfvar.json variable file for a component in a stack.

atmos terraform generate varfile <component> -s <stack> [flags]

Key flags:

• -f -- Custom output filename
• --dry-run, --process-templates, --process-functions, --skip

generate varfiles

Generate variable files for all components across stacks.

atmos terraform generate varfiles [flags]

generate backend

Generate a backend.tf.json file for a component in a stack.

atmos terraform generate backend <component> -s <stack> [flags]

Key flags:

• --dry-run, --process-templates, --process-functions, --skip

generate backends

Generate backend configuration files for all components across stacks.

atmos terraform generate backends [flags]

generate planfile

Generate a planfile in JSON or YAML format for review or tool integration.

atmos terraform generate planfile <component> -s <stack> [flags]

Key flags:

• --format -- Output format: json (default) or yaml
• --file / -f -- Custom planfile name or path
• --process-templates, --process-functions, --skip

Backend Management Commands

backend create

Provision backend infrastructure (S3 bucket, etc.) for a component.

atmos terraform backend create <component> --stack <stack>

backend list

List all backends in a stack.

atmos terraform backend list --stack <stack> [--format table|yaml|json]

backend describe

Show backend configuration for a component from the stack.

atmos terraform backend describe <component> --stack <stack> [--format table|yaml|json]

backend update

Update backend configuration (idempotent).

atmos terraform backend update <component> --stack <stack>

backend delete

Delete backend infrastructure (requires --force).

atmos terraform backend delete <component> --stack <stack> --force

Inspection and Utility Commands

output

Read Terraform output values from the state file.

atmos terraform output <component> -s <stack> [output_name] [flags]

Key flags:

• --format / -f -- Export format: json, yaml, hcl, env, dotenv, bash, csv, tsv, github
• --output-file / -o -- Write to file instead of stdout
• --uppercase / -u -- Convert keys to UPPERCASE
• --flatten -- Flatten nested maps into key_subkey format
• --skip-init -- Skip terraform init
• Native: -json, -raw, -state=PATH

validate

Validate Terraform HCL configuration files.

atmos terraform validate <component> -s <stack> [flags]

Key flags:

• --skip-init, --dry-run
• Native: -json, -no-color

console

Start an interactive Terraform console.

atmos terraform console <component> -s <stack>

shell

Start a shell pre-configured with component context.

atmos terraform shell <component> -s <stack> [flags]

Key flags:

• --dry-run, --process-templates, --process-functions, --skip

clean

Clean up Terraform files for a component or all components.

atmos terraform clean [<component> -s <stack>] [flags]

Key flags:

• --force / -f -- Skip confirmation prompt
• --everything -- Also delete state files (prompts for confirmation unless --force is set)
• --skip-lock-file -- Preserve .terraform.lock.hcl
• --cache -- Clean shared plugin cache
• --dry-run -- Show what would be deleted

show

Show the Terraform state or a saved plan.

atmos terraform show <component> -s <stack> [flags]

plan-diff

Compare two planfiles.

atmos terraform plan-diff <component> -s <stack> [flags]

Format and Code Quality Commands

fmt

Format Terraform configuration files.

atmos terraform fmt <component> -s <stack> [flags]

Resource Management Commands

import

Import existing infrastructure into Terraform state.

atmos terraform import <component> -s <stack> <address> <id>

taint

Mark a resource for recreation on next apply.

atmos terraform taint <component> -s <stack> <address>

untaint

Remove the taint from a resource.

atmos terraform untaint <component> -s <stack> <address>

force-unlock

Release a stuck state lock.

atmos terraform force-unlock <component> -s <stack> <lock-id>

refresh

Update state to match remote infrastructure (without modifying resources).

atmos terraform refresh <component> -s <stack> [flags]

Key flags:

• --skip-init, --dry-run
• Native: -target=RESOURCE, -var 'NAME=VALUE'

Additional Commands

get

Download and install modules referenced in configuration.

atmos terraform get <component> -s <stack>

graph

Generate a visual dependency graph.

atmos terraform graph <component> -s <stack>

providers

Show provider requirements.

atmos terraform providers <component> -s <stack>

version

Show the Terraform version.

atmos terraform version <component> -s <stack>

Source Management Commands

source pull

Pull component source code.

atmos terraform source pull <component> [flags]

source describe

Describe component source configuration.

atmos terraform source describe <component> [flags]

source delete

Delete pulled component source.

atmos terraform source delete <component> [flags]

source list

List component sources.

atmos terraform source list [flags]

Global Flags Available on All Commands

Flag	Description
--stack / -s	Target Atmos stack (required for most component operations, not needed for source commands)
--dry-run	Preview without executing
--process-templates	Enable/disable Go template processing
--process-functions	Enable/disable YAML function processing
--skip	Skip specific YAML functions
--identity	Override authentication identity