// the find
minamijoyo/tfmigrate
A Terraform / OpenTofu state migration tool for GitOps
tfmigrate is a CLI for doing Terraform/OpenTofu state surgery (mv, rm, import, replace-provider) as version-controlled HCL files instead of ad hoc `terraform state` commands. It's for teams running Terraform in production who need refactors (renames, splitting state into multiple directories) to go through the same review/CI pipeline as config changes, rather than someone running state commands by hand against prod.
The plan command actually validates the migration before touching anything: it computes the new state against a temporary local copy and fails if terraform plan still shows a diff, so you catch a wrong `mv` before it hits remote state. multi_state migrations handle moving resources between two separate state files/backends in one atomic-ish operation, which is the genuinely hard case when splitting a monorepo-style Terraform setup. Actions are plain strings that mirror real `terraform state` syntax (`mv foo bar`, `rm baz`), so there's no new DSL to learn, you're basically copy-pasting commands you already know into a file. History tracking with pluggable storage (local/S3/GCS) means unapplied migrations get picked up and applied in order automatically, which matters once you have more than a couple of these files sitting around.
It shells out to `terraform`/`tofu`/`terragrunt` as subprocesses, so you're exposed to whatever quirks your exact CLI version has, and the terragrunt case is messy enough that the README has to call out a version-dependent env var and a `remote_state.generate` requirement for dynamic state setups. There's no rollback if a multi_state apply fails partway between the from_dir and to_dir — you're left reconciling two states by hand, which is the exact scenario this tool exists to avoid. Terraform Cloud support is opt-in via a separate `is_backend_terraform_cloud` flag plus a workspace name in every migration file, easy to forget and get a confusing failure instead of a clear error. It's a single-maintainer project (minamijoyo) with a broad compatibility surface to hold up (Terraform 0.12+, OpenTofu 1.6+, Terragrunt across a CLI redesign) — fine for now given 1.2k stars and active pushes, but worth knowing before you build CI automation around it.