What does `terraform plan -detailed-exitcode` return, and how would you use it in a script?

## The default is deliberately blunt Run `terraform plan` and the process exits `0` on success and `1` on error. "Success" covers both an empty diff and a plan that destroys your database. For a human reading the terminal that is fine — the diff is right there. For anything automated it is useless, because the only way to distinguish the two outcomes is to scrape the output text, and output text is not an interface. ## Three codes instead of two ```bash terraform plan -detailed-exitcode ``` - `0` — succeeded, and the plan is empty; configuration and reality already agree. - `1` — the run errored: bad configuration, missing credentials, a provider failure, an uninitialised directory. - `2` — succeeded, and there are changes to apply. Code `2` is the interesting one, and note that it is a *success*. Nothing went wrong; Terraform is reporting a fact about the world. ## Two things it is good for **A scheduled comparison check.** Run a plan on a schedule against the committed configuration. Exit `0` means the estate still matches the code and nobody needs to know. Exit `2` means something diverged — a change merged but never applied, or someone altered infrastructure outside Terraform — and the job raises an alert with the diff attached. Exit `1` is a broken pipeline and pages differently, which is the second reason the three-way split matters: without it, a credentials failure looks identical to a clean run. **A conditional pipeline.** A plan stage that exits `0` can skip the apply stage — no approval request left sitting unanswered, no noise in the change log for a no-op. Exit `2` proceeds to review and apply. This works well combined with `-out`, since one run can both report the code and save the plan for the apply stage. ## The shell trap Most CI scripts run under `set -e`, which aborts on any non-zero exit. Under that setting a plan with changes kills the job, and the failure message will be unhelpfully generic. Capture the code explicitly instead: ```bash set +e terraform plan -input=false -detailed-exitcode -out=tfplan code=$? set -e case "$code" in 0) echo "no changes" ;; 2) echo "changes pending" ;; *) echo "plan failed"; exit "$code" ;; esac ``` The `||` idiom (`terraform plan -detailed-exitcode || code=$?`) works too, but the explicit `case` makes the intent readable to whoever debugs it at 3am. Either way, `1` must still fail the job — collapsing `1` and `2` into "non-zero, carry on" turns a broken pipeline into a silent one. ## What it does not tell you The exit code is a single bit of information: changes or no changes. It does not say whether those changes are additions or destructions, whether they are safe, or where they came from. For any judgement beyond "something differs", you need the plan itself — the human diff for a reviewer, or the JSON form for a policy tool. Treat `-detailed-exitcode` as the trigger, not the analysis. It also says nothing about *why* the diff is non-empty. An unapplied merged commit and an out-of-band console edit both produce `2`. Distinguishing them is a separate exercise; the exit code just tells the script that the exercise is now necessary. ## Interview framing This is a small, concrete detail, and it is usually asked as a proxy: does the candidate write infrastructure automation that reacts to results, or do they only run commands by hand? Being able to recite `0/1/2` and immediately name the `set -e` trap signals someone who has actually wired a plan into a scheduled job.