terraform plan Command Reference

Preview exactly what Terraform will change before it touches infrastructure.

terraform plan builds an execution plan from your configuration and current state. In CI you save the plan to a file so apply does exactly what was reviewed.

What it does

terraform plan compares desired configuration against state and real infrastructure, then prints the proposed create/update/destroy actions without making them. Saving with -out guarantees apply executes the reviewed plan.

Common flags and usage

-out=FILE: save the plan to a file for a later apply (the CI pattern)
-detailed-exitcode: exit 0 (no changes), 1 (error), or 2 (changes present)
-target=ADDR: plan only specific resources
-var / -var-file: set input variables
-input=false: never prompt (required in CI)

Example

shell

- name: Terraform Plan
  run: terraform plan -input=false -out=tfplan

- name: Terraform Apply
  if: github.ref == 'refs/heads/main'
  run: terraform apply -input=false tfplan

In CI

The reliable pattern is plan -out=tfplan then apply tfplan, ideally in the same job against the same locked state so the saved plan cannot go stale. Use -detailed-exitcode to gate a pipeline on whether changes exist (exit 2 = drift).

Key takeaways

plan previews changes; it never modifies infrastructure on its own.
Save the plan with -out=tfplan and feed that exact file to apply.
-detailed-exitcode returns 2 when changes are present, ideal for drift gates.