tenv

README

tenv

Terraform and OpenTofu version manager, written in Go.
· Report Bug · Request Feature

About The Project

Welcome to tenv, a versatile version manager for OpenTofu and Terraform, written in Go. Our tool simplifies the complexity of handling different versions of these powerful tools, ensuring developers and DevOps professionals can focus on what matters most - building and deploying efficiently.

tenv is a successor of tofuenv and tfenv.

Key Features

• Versatile version management: Easily switch between different versions of Terraform and OpenTofu.
• Semver 2.0.0 Compatibility: Utilizes go-version for semantic versioning and use the HCL parser to extract required version constraint from OpenTofu/Terraform files.
• Signature verification: Supports cosign (if present on your machine) and PGP (via gopenpgp) for verifying OpenTofu signatures. However, unstable OpenTofu versions are signed only with cosign (in this case, if cosign is not found tenv will display a warning).
• Intuitive installation: Simple installation process with Homebrew and manual options.

Table of Contents

Table of Contents

1. About The Project
   • Key Features
2. Table of contents
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
5. Environment variables
6. Version files
7. Technical details
8. Contributing
9. Community
10. Authors
11. Licence

Getting Started

Prerequisites

If you need to enable cosign checks, install cosign tool via one of the following commands:

MacOS (Homebrew)

brew install cosign

Alpine Linux

apk add cosign

Linux: RPM

LATEST_VERSION=$(curl https://api.github.com/repos/sigstore/cosign/releases/latest | grep tag_name | cut -d : -f2 | tr -d "v\", ")
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-${LATEST_VERSION}-1.x86_64.rpm"
sudo rpm -ivh cosign-${LATEST_VERSION}.x86_64.rpm

Linux: dkpg

LATEST_VERSION=$(curl https://api.github.com/repos/sigstore/cosign/releases/latest | grep tag_name | cut -d : -f2 | tr -d "v\", ")
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign_${LATEST_VERSION}_amd64.deb"
sudo dpkg -i cosign_${LATEST_VERSION}_amd64.deb

Installation

Automatic Installation

MacOS (Homebrew)

brew tap tofuutils/tap
brew install tenv

Ubuntu

TODO

Manual Installation

Get the most recent packaged binaries (.deb, .rpm, .apk, pkg.tar.zst , .zip or .tar.gz format) by visiting the release page. After downloading, unzip the folder and seamlessly integrate it into your system's PATH.

Docker Installation

You can use dockerized version of tenv via the following commands:

TODO

Usage

tenv supports OpenTofu and Terraform. To manage each binary you can use tenv subcommands (manage OpenTofu versions) or tenv tf subcommands (manage Terraform versions). Below is a list of commands that use actual subcommands: TOFUENV_

tenv (tool) install [version]

Install a requested version of (tool) (into (TOOL)_ROOT directory from (TOOL)_REMOTE url).

Without a parameter, the version to use is resolved automatically via TOFUENV_TOFU_VERSION or .opentofu-version files (searched in the working directory, user home directory, and TOFUENV_ROOT directory). Use "latest-stable" when none are found.

If a parameter is passed, available options include:

• an exact Semver 2.0.0 version string to install
• a version constraint string (checked against versions available at TOFUENV_REMOTE url)
• latest or latest-stable (checked against versions available at TOFUENV_REMOTE url)
• latest-allowed or min-required to scan your OpenTofu files to detect which version is maximally allowed or minimally required.

See required_version docs.

tenv install 1.6.0-beta5
tenv install "~> 1.6.0"
tenv install latest
tenv install latest-stable
tenv install latest-allowed
tenv install min-required

tenv (tool) use

Switch the default OpenTofu version to use (set in .opentofu-version file in TOFUENV_ROOT).

tenv use has a --working-dir, -w flag to write .opentofu-version file in working directory.

Available parameter options:

• an exact Semver 2.0.0 version string to use
• a version constraint string (checked against available in TOFUENV_ROOT directory)
• latest or latest-stable (checked against available in TOFUENV_ROOT directory)
• latest-allowed or min-required to scan your OpenTofu files to detect which version is maximally allowed or minimally required.

See required_version docs.

tenv use min-required
tenv use v1.6.0-beta5
tenv use latest
tenv use latest-allowed

tenv (tool) detect

Detect the used version of OpenTofu for the working directory.

$ tenv detect
OpenTofu 1.6.0 will be run from this directory.

tenv (tool) reset

Reset used version of OpenTofu (remove .opentofu-version file from TOFUENV_ROOT).

tenv reset

tenv (tool) uninstall [version]

Uninstall a specific version of OpenTofu (remove it from TOFUENV_ROOT directory without interpretation).

tenv uninstall v1.6.0-alpha4

tenv (tool) list

List installed OpenTofu versions (located in TOFUENV_ROOT directory), sorted in ascending version order.

tenv list has a --descending, -d flag to sort in descending order.

$ tenv list
  1.6.0-rc1 
* 1.6.0 (set by /home/dvaumoron/.tenv/.opentofu-version)

tenv (tool) list-remote

List installable OpenTofu versions (from TOFUENV_REMOTE url), sorted in ascending version order.

tenv list-remote has a --descending, -d flag to sort in descending order.

tenv list-remote has a --stable, -s flag to display only stable version.

$ tenv list-remote
1.6.0-alpha1
1.6.0-alpha2
1.6.0-alpha3
1.6.0-alpha4
1.6.0-alpha5
1.6.0-beta1
1.6.0-beta2
1.6.0-beta3
1.6.0-beta4
1.6.0-beta5
1.6.0-rc1 (installed)
1.6.0 (installed)

tenv help [command]

Help about any command.

You can use --help -h flag instead.

$ tenv help tf detect
Display Terraform current version.

Usage:
  tenv tf detect [flags]

Flags:
  -f, --force-remote        force search on versions available at TFENV_REMOTE url
  -h, --help                help for detect
  -k, --key-file string     local path to PGP public key file (replace check against remote one)
  -n, --no-install          disable installation of missing version
  -u, --remote-url string   remote url to install from (default "https://releases.hashicorp.com/terraform")

Global Flags:
  -r, --root-path string   local path to install versions of OpenTofu and Terraform (default "/home/dvaumoron/.tenv")
  -v, --verbose            verbose output

$ tenv use -h
Switch the default OpenTofu version to use (set in .opentofu-version file in TOFUENV_ROOT)

Available parameter options:
- an exact Semver 2.0.0 version string to use
- a version constraint string (checked against versions available in TOFUENV_ROOT directory)
- `latest` or `latest-stable` (checked against versions available in TOFUENV_ROOT directory)
- `latest-allowed` or `min-required` to scan your OpenTofu files to detect which version is maximally allowed or minimally required.

Usage:
  tenv use version [flags]

Flags:
  -f, --force-remote          force search on versions available at TOFUENV_REMOTE url
  -t, --github-token string   GitHub token (increases GitHub REST API rate limits)
  -h, --help                  help for use
  -k, --key-file string       local path to PGP public key file (replace check against remote one)
  -n, --no-install            disable installation of missing version
  -u, --remote-url string     remote url to install from (default "https://api.github.com/repos/opentofu/opentofu/releases")
  -w, --working-dir           create .opentofu-version file in working directory

Global Flags:
  -r, --root-path string   local path to install versions of OpenTofu and Terraform (default "/home/dvaumoron/.tenv")
  -v, --verbose            verbose output

Environment variables

tenv commands support two groups of environment variables, one for managing OpenTofu and one for managing Terraform

OpenTofu environment variables

TOFUENV_AUTO_INSTALL

String (Default: true)

If set to true tenv will automatically install a missing OpenTofu version needed (fallback to latest-allowed strategy when no .opentofu-version files are found).

tenv subcommands detect and use support a --no-install, -n disabling flag version.

Example:

Use OpenTofu version 1.6.1 that is not installed, and auto installation is disabled. (-v flag is equivalent to TOFUENV_VERBOSE=true):

$ TOFUENV_AUTO_INSTALL=false tenv use -v 1.6.1
Write 1.6.1 in /home/dvaumoron/.tenv/.opentofu-version

Example:

Use OpenTofu version 1.6.0 that is not installed, and auto installation stay enabled.

$ tenv use -v 1.6.0
Installation of OpenTofu 1.6.0
Write 1.6.0 in /home/dvaumoron/.tenv/.opentofu-version

TOFUENV_FORCE_REMOTE

String (Default: false)

If set to true tenv detection of needed version will skip local check and verify compatibility on remote list.

tenv subcommands detect and use support a --force-remote, -f flag version.

TOFUENV_OPENTOFU_PGP_KEY

String (Default: "")

Allow to specify a local file path to OpenTofu PGP public key, if not present download https://get.opentofu.org/opentofu.asc.

tenv subcommands detect, ìnstall and use support a --key-file, -k flag version.

TOFUENV_REMOTE

String (Default: https://api.github.com/repos/opentofu/opentofu/releases)

To install OpenTofu from a remote other than the default (must comply with Github REST API).

tenv tf subcommands detect, install, list-remote and use support a --remote-url, -u flag version.

TOFUENV_ROOT

String (Default: ${HOME}/.tenv)

The path to a directory where the local OpenTofu versions, Terraform versions and tenv configuration files exist.

tenv support a --root-path, -r flag version.

TOFUENV_GITHUB_TOKEN

String (Default: "")

Allow to specify a GitHub token to increase GitHub Rate limits for the REST API. Useful because OpenTofu binares are downloaded from the OpenTofu GitHub repository.

tenv subcommands detect, install, list-remote and use support a --github-token, -t flag version.

TOFUENV_VERBOSE

String (Default: false)

Active the verbose display of tenv.

tenv support a --verbose, -v flag version.

TOFUENV_TOFU_VERSION

String (Default: "")

If not empty string, this variable overrides OpenTofu version, specified in .opentofu-version files. tenv subcommands install and detect also respects this variable.

e.g. with :

$ tofu version
OpenTofu v1.6.0
on linux_amd64

then :

$ TOFUENV_TOFU_VERSION=1.6.0-rc1 tofu version
OpenTofu v1.6.0-rc1
on linux_amd64

Terraform environment variables

TFENV_AUTO_INSTALL

String (Default: true)

If set to true tenv will automatically install a missing Terraform version needed (fallback to latest-allowed strategy when no .terraform-version files are found).

tenv tf subcommands detect and use support a --no-install, -n disabling flag version.

Example: Use Terraform version 1.6.0-rc1 that is not installed, and auto installation is disabled. (-v flag is equivalent to TFENV_VERBOSE=true)

$ TFENV_AUTO_INSTALL=false tenv tf use -v 1.6.0-rc1
Write 1.6.0-rc1 in /home/dvaumoron/.tenv/.terraform-version

Example: Use Terraform version 1.6.0-rc1 that is not installed, and auto installation stay enabled.

$ tenv tf use -v 1.6.0-rc1
Installation of Terraform 1.6.0-rc1
Write 1.6.0-rc1 in /home/dvaumoron/.tenv/.terraform-version

TFENV_FORCE_REMOTE

String (Default: false)

If set to true tenv detection of needed version will skip local check and verify compatibility on remote list.

tenv tf subcommands detect and use support a --force-remote, -f flag version.

TFENV_HASHICORP_PGP_KEY

String (Default: "")

Allow to specify a local file path to Hashicorp PGP public key, if not present download https://www.hashicorp.com/.well-known/pgp-key.txt.

tenv tf subcommands detect, ìnstall and use support a --key-file, -k flag version.

TFENV_REMOTE

String (Default: https://releases.hashicorp.com/terraform)

To install Terraform from a remote other than the default (must comply with Hashicorp Release API)

tenv tf subcommands detect, install, list-remote and use support a --remote-url, -u flag version.

TFENV_ROOT

Path (Default: `$HOME/.tenv`)

The path to a directory where the local Terraform versions, OpenTofu versions and tenv configuration files exist.

tenv tf support a --root-path, -r flag version.

TFENV_VERBOSE

String (Default: false)

Active the verbose display of tenv.

tenv tf support a --verbose, -v flag version.

TFENV_TERRAFORM_VERSION

String (Default: "")

If not empty string, this variable overrides Terraform version, specified in .terraform-version files. tenv subcommands install and detect also respects this variable.

e.g. with :

$ terraform version
Terraform v1.6.0
on linux_amd64

then :

$ TFENV_TERRAFORM_VERSION=1.6.0-rc1 terraform version
Terraform v1.6.0-rc1
on linux_amd64

version files

.opentofu-version file

If you put a .opentofu-version file in the working directory, user home directory, or TOFUENV_ROOT directory, tenv detects it and uses the version written in it. Note, that TOFUENV_TOFU_VERSION can be used to override version specified by .opentofu-version file.

Recognized values (same as tenv use command):

• an exact Semver 2.0.0 version string to use
• a version constraint string (checked against versions available in TOFUENV_ROOT directory)
• latest or latest-stable (checked against versions available in TOFUENV_ROOT directory)
• latest-allowed or min-required to scan your OpenTofu files to detect which version is maximally allowed or minimally required.

See required_version docs.

.terraform-version file

TODO

terragrunt.hcl file

TODO

Technical details

Project binaries

tofu

The tofu command in this project is a proxy to OpenTofu's tofu command managed by tenv. The default resolution strategy is latest-allowed (without TOFUENV_TOFU_VERSION environment variable or .opentofu-version file).

terraform

The terraform command in this project is a proxy to HashiCorp's terraform command managed by tenv. The default resolution strategy is latest-allowed (without TFENV_TERRAFORM_VERSION environment variable or .terraform-version file).

Terraform support

tenv relies on .terraform-version files, TFENV_HASHICORP_PGP_KEY, TFENV_REMOTE and TFENV_TERRAFORM_VERSION specifically to manage Terraform versions.

tenv tf have the same managing subcommands for Terraform versions (detect, install, list, list-remote, reset, uninstall and use).

tenv checks the Terraform PGP signature (there is no cosign signature available).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Community

Have questions or suggestions? Reach out to us via:

• GitHub Issues
• User/Developer Group: Join github community to get update of Harbor's news, features, releases, or to provide suggestion and feedback.
• Slack: Join tofuutils's community for discussion and ask questions: OpenTofu, channel: #tofuutils

Authors

tenv is based on tofuenv and gotofuenv projects and supported by tofuutils team with help from these awesome contributors:

LICENSE

The tenv project is distributed under the Apache 2.0 license. See LICENSE.