Terramate: Git-based orchestration for existing Terraform and OpenTofu projects

The problem Terramate solves is state sprawl, not Terraform itself

Terramate does not replace Terraform. The README describes it as an orchestration and code generation engine that lets IaC such as Terraform, OpenTofu, Terragrunt and Kubernetes scale. The target user is a platform or infrastructure team that already has working Terraform and has hit one of two walls: a state file so large that every plan touches everything, or a directory tree where the same backend and provider blocks are copy-pasted into dozens of modules.

The README's first benefit is breaking up large monolithic state files into multiple smaller stacks to limit blast radius and reduce runtimes. The second is reducing duplication by generating native Terraform backend and provider configuration, or any other arbitrary file, through the Terramate compiler. Those are concrete, mechanical problems. Nothing here asks you to rewrite modules or move state through a migration tool.

Who it is not for: a single-team project with one state file and three modules. The overhead of a stack graph, a change-detection model and an HCL configuration layer only pays back once the number of deployable units is large enough that running everything on every commit is wasteful.

Stacks, a Git diff, and a dependency graph decide what runs

The mechanism has three parts. First, the repository is divided into stacks, each a directory with its own Terramate configuration. Second, change detection compares the current commit against a base, using Git, and decides which stacks contain changes. The README states that this detection also covers referenced Terraform and OpenTofu modules and Terragrunt dependencies, which matters because a change to a shared module should trigger every stack that consumes it, not just the directory where the file lives.

Third, orchestration runs commands across the selected stacks. The README calls it a graph-based orchestration engine and says dependencies among environments are managed with output sharing. So stack B can depend on an output from stack A, and the engine orders execution accordingly rather than relying on directory naming conventions.

The claim that Terramate does not require access to your state backend, your code or your cloud accounts is the design consequence of all this. The CLI reads the Git repository and the HCL configuration, computes a plan of what to run, and shells out to Terraform or Terragrunt. It is a coordinator sitting beside your existing tooling, not a control plane holding credentials.

Installing Terramate CLI and onboarding an existing project

The README gives two installation paths. Homebrew is the shortest on macOS and Linux:

brew install terramate

If you prefer to build from source, the Go toolchain path installs the CLI from the module path:

go install github.com/terramate-io/terramate/cmd/...@latest

After either command, a `terramate` binary should be on your PATH. The README points to the installation documentation page for other methods, and that page is where you should look for Windows or container-based installs, since the README does not spell those out.

Onboarding is where the design shows. The README says Terramate can be onboarded to any existing Terraform, OpenTofu or Terragrunt project with a single command and without requiring any refactoring, and links separate onboarding guides for each of the three. Orchestration is then expressed as a command you already know, wrapped by the CLI. The README's own example of orchestration is running `terraform apply` in stacks, and change detection decides which stacks are included.

If you want the optional cloud features, the README gives one command to authenticate:

terramate cloud login

That step is only needed for Terramate Cloud, which is a separate managed service. Note that the README does not document rollback for a partially applied run, so a failed apply mid-graph is something you handle with your own Terraform state procedures.

Code generation is the part that replaces copy-paste

The generation feature is configured in HCL, which is the same language Terraform users already read. The repository contains files such as `generate_mkconfig.tm` and `generate_preview.tm`, and the README says generation can emit HCL, JSON and YAML. The practical use is a single definition of a backend block that is rendered into every stack, so changing the bucket or the state key prefix is a one-line edit rather than a search and replace across fifty directories.

This is also where the trade-off sits. Generated files are still files. If a teammate edits a generated backend block by hand, the next generation pass will either overwrite it or conflict with it, and the README does not describe a merge strategy. Teams adopting generation should decide early which files are generated and which are hand-written, and keep the two sets disjoint. That is a convention problem, not a tool problem, but the tool does not solve it for you.

Where the CLI stops and Terramate Cloud starts

The README is explicit that the CLI can optionally be paired with Terramate Cloud, described as a fully managed SaaS service that adds features for managing and observing infrastructure across one or multiple repositories. The list of cloud-side capabilities includes observability, drift detection, asset management, misconfiguration detection, incident management, developer self-service with scaffolding, and Slack notifications.

That split is the single most important thing to understand before evaluating Terramate. Drift detection, which many teams assume is a core orchestration feature, is listed under the cloud product, not the CLI. The same is true of asset management and notifications. If your evaluation criteria are a drift dashboard and a Slack alert when production diverges, the open-source CLI alone will not deliver them.

The counterweight is that the CLI is genuinely standalone. The README states that using Terramate does not require running or maintaining additional infrastructure, and that it needs no access to state or cloud accounts. A team that only wants stack orchestration and code generation, and is comfortable with CI logs as its observability, can use the CLI and ignore the cloud entirely.

Terramate versus Terragrunt: two different places to put the logic

The comparison people ask about is Terragrunt, and the difference is architectural rather than feature-list. Terragrunt is a Terraform wrapper: you invoke Terragrunt instead of Terraform, and it handles remote state configuration, dependency blocks between modules, and input propagation. Terramate does not wrap the binary. The README's example orchestration runs `terraform apply` in stacks, and the CLI shells out to whatever command you configure.

That means Terramate can orchestrate Terragrunt just as well as Terraform, and indeed the repository's `go.mod` lists `github.com/gruntwork-io/terragrunt` as a dependency, with dedicated onboarding documentation for existing Terragrunt projects. The two are not mutually exclusive.

The practical difference is where configuration lives. With Terragrunt, dependency wiring and state configuration are expressed in Terragrunt HCL that only Terragrunt understands. With Terramate, stack metadata and generation rules live in Terramate HCL, and the orchestration target is an arbitrary command. The README frames the benefit as no lock-in: on- and off-board at any point, because removing Terramate leaves the underlying Terraform and Terragrunt files intact.

Licence, maintenance and what an upgrade actually costs

Terramate is licensed under MPL-2.0, a file-level copyleft licence. In practice that means modifications to existing Terramate source files must be published under the same licence, while larger works that merely combine with it are not automatically covered. The repository also ships a `ThirdPartyNotice.txt` file, which is where you should look for the dependency licences that flow through a Go binary. This is a description of the licence text, not legal advice; if you redistribute a modified binary, have counsel read the MPL.

The repository is not archived, and the last push was on 2026-09-08, with v0.17.3 released the same day and a release candidate v0.17.3-rc1 on 2026-09-02. The version numbering matters more than the cadence: the project is still on 0.x, which conventionally signals that interfaces can change between minor releases. The repository carries a CHANGELOG.md and a VERSION file, so the upgrade path is at least documented in-tree.

Upgrade cost is low for the CLI itself, since it is a single binary installed by brew or `go install`. The real cost is in your `.tm` configuration files and any generated output, which you should regenerate and diff after each minor bump. Pin the version in CI rather than tracking `@latest`.

Editorial conclusion

Adopt Terramate CLI if you already run Terraform, OpenTofu or Terragrunt at a scale where monolith state files and repeated backend blocks hurt, and you want to keep your existing CI/CD. Skip it if you expect a GUI-first platform or want drift detection and asset inventory without running a second system, because the README places those in Terramate Cloud. Before committing, verify two things on your own repository: that onboarding produces a stack layout you can live with, and that your CI runner has a full Git history, since change detection is built on top of Git.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. Project website
3. README
4. Releases
5. terramate-io/terramate on GitHub