tfclean for Mac

tfclean is a tool for cleaning up Terraform configuration files by automatically removing applied moved, import, and removed blocks. This helps maintain clean and readable Terraform configurations by eliminating blocks that have already served their purpose.

Installation

Using Homebrew

Using go install

Using aqua

aqua is a declarative CLI Version Manager. You can install tfclean using aqua:

Or add to your aqua.yaml:

Then run:

Using GitHub Actions

You can use the official GitHub Action to install tfclean in your workflows:

Manual Installation

Download the appropriate binary for your system from the releases page.

Usage

Remove All Blocks

Remove all moved/import/removed blocks regardless of their state:

Remove Only Applied Blocks

Remove only the blocks that have been successfully applied (requires access to tfstate).

When using an S3 backend, you can omit --tfstate. tfclean auto-detects the state location by reading terraform { backend "s3" { ... } } from .tf files in the given directory.

Multiple tfstate Files

When the same Terraform configuration is backed by several states — for example one per developer, per PR, and dev/prod — pass --tfstate multiple times. A block is removed only if it has been applied in all of the given states; if it is still pending in any one of them, tfclean keeps it.

In the example above, a moved block that has been applied to dev-alice and prod but not yet to dev-bob is preserved until it is applied everywhere. Because dropping a state could remove a block that is still pending elsewhere, tfclean treats a failure to read any explicitly given state as a fatal error rather than silently skipping it.

Auto-detection only resolves a single backend from your .tf files, so multiple states must be specified explicitly with --tfstate.

Child Modules

Refactorings such as splitting a module leave moved / removed blocks inside a child module. tfclean cleans those too.

tfclean follows module blocks whose source is a local path (./ or ../), recursively, and cleans the .tf files in those directories that are inside the given directory (e.g. ./modules/x). Remote modules (registry, git, etc.) are never touched. Addresses inside a child module are relative to the module, so tfclean checks them against every instance of the module in the state (module.x, module.x[0], module.x["a"], and every caller if the module is called from several places). A block is removed only if it has been applied for all of those instances.

tfclean keeps a child module's blocks when it cannot find the module (or one of its parent instances has none of it) in the state, since its resources may still be under an old address that a pending moved block elsewhere will bring there.

Modules outside the given directory