New nametfv is now teriac. See what changed and how to move over.
v0.2.1
teriac CLI How it works

How the CLI works

What happens when you install, switch and run a version with teriac: the setup, the download and checksum check, the store layout, and why terraform and teriac always run the same binary.

teriac installs, switches and manages several versions of Terraform, Terragrunt and OpenTofu, without sudo. Every binary lives in ~/.teriac/, so upgrading teriac itself never removes the versions you installed.

Signed installs, OpenTofu and Terragrunt, switching versions, auto-switch on cd, pinning, plan and apply by file, and doctor.

The short version

npm install -g @marcdomain/teriac

teriac install latest            # latest Terraform
teriac install latest -p tofu    # latest OpenTofu
teriac install latest -p tg      # latest Terragrunt
teriac use 1.9.0                 # switch Terraform
teriac pin                       # write .terraform-version for your team
eval "$(teriac shell-init zsh)"  # switch automatically on cd

From install to terraform plan

npm install -g @marcdomain/teriac
       │
       ▼
first `teriac` run (and after each upgrade)
  ├── creates ~/.teriac/bin/, ~/.teriac/store/, ~/.teriac/cache/
  └── adds ~/.teriac/bin to PATH (shell configs / Windows registry)
       │
       ▼
teriac install 1.9.0
  ├── fetches version list  →  ~/.teriac/cache/terraform-versions.json  (1hr TTL)
  ├── downloads zip         →  system temp dir  (with progress bar)
  ├── verifies SHA256       →  the release's SHA256SUMS file
  ├── extracts binary only  →  ~/.teriac/store/terraform/1.9.0
  └── records arch          →  ~/.teriac/store/terraform/arch.json
       │
       ▼
teriac use 1.9.0
  ├── copies ~/.teriac/store/terraform/1.9.0  →  ~/.teriac/bin/terraform
  └── writes active version  →  ~/.teriac/active.json
       │
       ▼
terraform plan   ← resolves to ~/.teriac/bin/terraform  (same binary as teriac)
teriac plan      ← spawns ~/.teriac/bin/terraform directly (no PATH lookup)

terraform and teriac always run the exact same binary.

Step by step

  1. Setup. teriac has no install script. The first time you run it, and after every upgrade, it creates its folders and puts ~/.teriac/bin first on your PATH. A marker file records which teriac version finished setup, so this only happens once per version.
  2. Version list. install latest and patch ranges like 1.9.^ need the list of releases. It's fetched from HashiCorp (Terraform) or the GitHub API (OpenTofu, Terragrunt) and cached for an hour.
  3. Download. The release archive goes to your system temp folder, with a progress bar.
  4. Checksum. Every download (Terraform, Terragrunt and OpenTofu) is checked against the release's published SHA256SUMS file before anything is extracted. A mismatch stops the install.
  5. Store. Only the binary is extracted, renamed to its version number, and kept in the store. Its architecture is recorded in arch.json.
  6. Switch. use copies the binary from the store into ~/.teriac/bin. No symlinks, no sudo, and it works the same on Windows.

Store layout

~/.teriac/
  bin/
    terraform          ← active terraform binary (no sudo, no symlinks)
    tofu               ← active opentofu binary
    terragrunt         ← active terragrunt binary
  store/
    terraform/
      1.9.0            ← installed versions (binary renamed to version number)
      1.7.3
      arch.json        ← { "1.9.0": "arm64", "1.7.3": "amd64" }
    opentofu/
      1.8.0
      arch.json
    terragrunt/
      1.2.1
      arch.json
  cache/
    terraform-versions.json   ← remote list cached for 1 hour
    opentofu-versions.json
  active.json          ← { "terraform": "1.9.0", "opentofu": null, "terragrunt": "1.2.1" }

Each tool has its own store folder and its own active version, so switching Terraform never touches OpenTofu or Terragrunt.

Moving the store

Set TERIAC_HOME to keep everything in another folder. The shell hook, PATH line and completions all follow it:

export TERIAC_HOME="$HOME/.local/share/teriac"

Tools and providers

Every command takes --provider (-p) to pick the tool. Terraform is the default.

Tool --provider values Binary Store
Terraform terraform (default) ~/.teriac/bin/terraform ~/.teriac/store/terraform/
OpenTofu tofu, opentofu ~/.teriac/bin/tofu ~/.teriac/store/opentofu/
Terragrunt terragrunt, tg ~/.teriac/bin/terragrunt ~/.teriac/store/terragrunt/

What's next