# terraform-switcher: Installing and Switching Terraform Versions from the CLI

> terraform-switcher is a Go command-line tool that installs, verifies, and selects Terraform versions without requiring each version to be installed beforehand. It fits developers who need quick version changes, but its documentation leaves configuration discovery and rollback details outside the core quick start.

**warrensbox/terraform-switcher** — A command line tool to switch between different versions of terraform  (install with homebrew and more)

- Repository: https://github.com/warrensbox/terraform-switcher
- Website: https://tfswitch.warrensbox.com
- Stars: 1,487 · Forks: 147
- Language: Go
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/warrensbox-terraform-switcher

## The Terraform Version Problem tfswitch Addresses

terraform-switcher, usually invoked as `tfswitch`, targets the operational friction around having multiple Terraform versions available on one machine. A developer may need Terraform 1.7.0 for one project and another version for a different repository. Without a version manager, that commonly means locating the appropriate binary, installing it, and changing which executable Terraform resolves to. The README does not present tfswitch as a replacement for Terraform configuration management, state storage, or infrastructure orchestration. Its stated job is narrower: obtain and select the Terraform version a user requests.

The intended users are command-line users who know which Terraform version they want, as well as users who prefer choosing it interactively. The documentation states that `tfswitch` downloads and verifies a requested version when it is not already installed. That distinction matters. The tool is not only a symlink switcher for binaries that the user has already installed. It is also intended to handle the acquisition and verification step.

This makes the project most relevant to developers moving between Terraform CLI releases, including local experimentation across repositories. It is less compelling for a workstation committed permanently to one Terraform version. The value comes from reducing repeated version-selection work, not from changing Terraform configuration syntax or managing providers. The README does not claim that tfswitch keeps multiple project modules isolated or records version selections inside a repository, so those capabilities should not be assumed.

## Selection, Download, and Verification in tfswitch

The documented interaction has two paths. Running `tfswitch` without a version opens a dropdown menu from which the user selects a Terraform version. Passing a version on the command line skips that selection step and targets an exact release, such as `1.7.0`. After selection, an already installed version can be used, while a missing version is downloaded and verified according to the README's description.

The repository is a Go program whose module is named `github.com/warrensbox/terraform-switcher`. Its `go.mod` declares Go 1.26.0 and dependencies associated with interactive prompts, version handling, configuration, terminal support, and PGP verification. The command is built from `main.go` and the code under `lib/`. That layout supports the description of tfswitch as a compiled CLI rather than a shell-only alias manager. Its dependencies also support the visible menu through a prompt library and release selection through version comparison logic, although the README excerpt does not describe every internal function.

The practical data flow is short: the user supplies a version or selects one, `tfswitch` resolves the requested Terraform release, and the selected binary becomes the one the user can invoke. The available documentation does not state the internal cache directory, download URL construction, verification algorithm, or exact replacement mechanism for the active binary. Those are implementation details that should be checked in the extended documentation or source before using tfswitch in a tightly managed environment. The visible guarantee is narrower: the desired version can be downloaded, verified if absent, and selected through the CLI.

## Installing tfswitch on Homebrew, Linux, and Windows

For macOS and Linux systems that already have Homebrew, the recommended installation is the official Homebrew formula:

```bash
brew install tfswitch
```

After Homebrew completes the installation, `tfswitch` should be available as a command. The README specifically says that the official formula is the recommended method for most users. It also provides a maintainer tap for users who want a newly published release before it reaches the main Homebrew repository:

```bash
brew install warrensbox/tap/tfswitch
```

The tap is an explicit distribution choice rather than a necessary part of normal setup. On Linux, the documented shell installer is:

```bash
curl -L https://raw.githubusercontent.com/warrensbox/terraform-switcher/master/install.sh | bash
```

This command downloads and pipes the repository's `install.sh` into Bash. The README documents it for Linux, but it does not describe a checksum, prompt, dry-run option, or preview of the script. Windows users are directed to the latest release page to download and extract a compatible binary. The listed Windows builds cover 386, amd64, arm6, and arm7 CPU structures, so architecture must be checked before extraction.

Homebrew documentation notes a separate platform constraint: Homebrew on Linux requires at least Homebrew v5.0.6. That requirement applies to the package manager, not to a tfswitch release. For Windows, the release page is the authoritative place to inspect the available binary rather than assuming that the Linux installer works.

## First Use with a Version Menu and an Exact Version

The shortest real use is to run tfswitch with a version. The README gives this exact example:

```bash
tfswitch 1.7.0
```

Replace `1.7.0` with the required Terraform release. According to the documentation, tfswitch installs that version if it is missing and verifies it, or selects it if it is already installed. At this point, the reader should be able to invoke Terraform using the selected installation. The README does not print the subsequent `terraform version` output, so it does not establish the exact success text or formatting.

For interactive selection, run:

```bash
tfswitch
```

This opens the documented dropdown. Selecting an entry is the alternative to providing a version argument. The menu is useful when a developer does not remember the full release number. The command-line form is more deterministic for scripts and repeated local commands because the requested release is visible in the invocation.

A first-use check should therefore cover two observable facts: whether tfswitch installs or reuses the requested release, and whether the Terraform command available afterward corresponds to that version. The README's extended usage guide is linked for additional command-line behavior. Its excerpt does not document aliases, a persistent global default, rollback commands, offline installation, or cleanup behavior, so the exact one-version flow should be used as the initial validation boundary.

## Building from Source and the Go 1.26.0 Boundary

Users who prefer a source build can clone the repository and invoke its Makefile. The README names `make tfswitch` as the build command and states that the resulting binary is created in the `build` directory. The documented install target is `make install`, which installs the binary to `~/bin/` on supported platforms.

A source build has a stricter toolchain expectation than downloading a release binary. The repository's `go.mod` declares:

```text
go 1.26.0
```

This is an exact repository requirement to verify before cloning and building. The Makefile locates the Go binary using the Go version declared in `go.mod`, but it also allows selection through the `GOBINARY` variable. If the expected toolchain is installed but not discovered correctly, the documented build mechanism is to set `GOBINARY` to its executable path.

The source route is relevant when users want control over compilation, produce a binary for their own environment, or contribute changes. It is less convenient than Homebrew for routine installation. Build dependencies also change when `go.mod` changes, so an automation system pinned to an older repository state may need a different Go toolchain. The MIT license permits use and modification under its terms, but consumers still need to retain required notices and comply with the license text. The LICENSE file is the source for those obligations.

## Operational Limits, Distribution Trade-offs, and Manual Installation

The clearest limitation is that tfswitch centers its workflow on an explicitly selected Terraform release. The README does not say that the quick-start command scans the current working directory, reads a Terraform version constraint, or chooses a release automatically from project files. Although `go.mod` includes HCL-related dependencies, that fact alone does not justify claiming automatic configuration parsing. A team whose primary requirement is declarative version selection should verify those behaviors in the extended command-line documentation first.

The distribution options also involve trade-offs. The official Homebrew formula is the normal path for macOS and many Linux installations, while the maintainer tap can expose a new release earlier. The Linux shell command is convenient but executes content fetched from the repository's `master` branch. Its use requires trusting that branch and the network path at installation time. Windows requires manual download, extraction, architecture selection, and PATH configuration not fully described in the README.

A real alternative is direct management of HashiCorp release binaries. That approach gives the user explicit control over which archive is downloaded and where each executable is placed, but it does not provide tfswitch's documented dropdown, missing-version download, and verification flow. Homebrew is a separate alternative when Terraform formulas alone meet the need, but it is not the same mechanism as selecting a requested version through tfswitch.

Maintenance has a concrete recent signal. The repository is not archived, its last push was on 2026-10-15, and release v1.20.0 was published on 2026-09-28. Upgrade automation must account for the documented version-format change from an old identifier such as `0.1.2412` to Go-style identifiers such as `v1.0.3` and `v1.0.0`. Parsers that expect the old format can fail even when the underlying binary remains functional.

## Conclusion

Developers who repeatedly switch among named Terraform versions should consider tfswitch, especially when manual download and installation would be inconvenient. Teams should not adopt it solely as a configuration compatibility scanner, since the README does not document automatic version inference. Before adoption, verify the package source, target platform support, required Go version for source builds, and whether CI expects the new `v`-prefixed tfswitch version format.

## FAQ

### How do I install terraform-switcher with Homebrew?

Run `brew install tfswitch`. The README identifies the official Homebrew formula as the recommended installation method for most users.

### How do I select a specific Terraform version with tfswitch?

Run `tfswitch 1.7.0` and replace `1.7.0` with the desired release. The documentation states that a missing version is downloaded and verified before selection.

### Can tfswitch choose Terraform versions from a dropdown menu?

Yes. Running `tfswitch` without a version opens the dropdown menu documented in the quick start.

## Sources

- [License: MIT](https://github.com/warrensbox/terraform-switcher/blob/master/LICENSE)
- [Project website](https://tfswitch.warrensbox.com)
- [README](https://github.com/warrensbox/terraform-switcher/blob/master/README.md)
- [Releases](https://github.com/warrensbox/terraform-switcher/releases)
- [warrensbox/terraform-switcher on GitHub](https://github.com/warrensbox/terraform-switcher)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/warrensbox-terraform-switcher