# Terraform init flags: -upgrade, -reconfigure, -migrate-state mean different things
## Why
`terraform init` does two jobs: install providers/modules, and configure the backend. Its flags target one job each, and mixing them up is how backends get rebound to the wrong state or provider upgrades happen by accident.
## The flags
1. Plain `terraform init`. Installs what is missing, configures the backend if not already configured. Safe to rerun; it changes nothing once set up.
2. `-upgrade`. Re-resolves providers and modules to the newest allowed versions and rewrites the lock file. This is a deliberate upgrade action, not hygiene.
3. `-reconfigure`. Discards the existing backend configuration and reconfigures from scratch, without migrating state. Use when the backend settings changed but the state stays where it is. The old state file is left behind, not moved.
4. `-migrate-state`. Moves state from the old backend to the new one when the backend block changed. Terraform asks which state to keep when both exist.
## Rules for agents
1. Backend block changed? You need `-reconfigure` or `-migrate-state`. Plain init will error telling you exactly this; read the error instead of guessing flags.
2. Never `-migrate-state` without a backup of the current state (`terraform state pull > backup.json` first).
3. `-upgrade` in CI is a policy decision, not a default. Pin it behind an explicit upgrade job.
4. If init says the backend config changed and you did not change it, stop. Something or someone else did; find out what before proceeding.