Skip to main content
from-tofuenv.md7.0 KB
View on GitHub

Replace tofuenv with the Atmos Toolchain

This reference describes how to replace tofuenv with the Atmos toolchain. For the decision guide, see ../SKILL.md. For the full toolchain feature reference, see atmos-toolchain.

The user can also manage Terraform versions with tfenv, or Terragrunt versions with tenv. In that case, see from-tfenv.md and from-tenv.md. The steps are the same. Only the tool differs.

Overview

tofuenv has one purpose. It pins an OpenTofu version. Use an .opentofu-version file (a single bare version string), or use the tofuenv use X.Y.Z command.

The Atmos equivalent is one line in .tool-versions. For the common case, this migration is mechanical. The one gap is tofuenv's partial or range-based version selectors. See Functional Gaps.

Before / After

Before:

# .opentofu-version
1.10.3

You can also set the version with the tofuenv use 1.10.3 command. This command switches the active version by recording it in ~/.tofuenv/version, the global default. It does not write .opentofu-version. To write a per-project pin instead, run tofuenv use 1.10.3 followed by tofuenv pin. tofuenv pin writes the currently active version to .opentofu-version in the current directory.

After:

# .tool-versions
opentofu 1.10.3
# atmos.yaml
toolchain:
  aliases:
    opentofu: opentofu/opentofu
  registries:
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/pkgs
      ref: v4.550.0
      priority: 10
components:
  terraform:
    command: tofu # tell Atmos to invoke the OpenTofu binary
atmos toolchain install

Steps

  1. Read the current pin. Run cat .opentofu-version if the file exists. Otherwise, run tofuenv version-name to find the active version.
  2. Add the version to .tool-versions. Append opentofu <version>. Create the file if it does not exist.
  3. Add the toolchain: block to atmos.yaml if the repository does not already have one. Set components.terraform.command: tofu. This makes atmos terraform invoke OpenTofu instead of Terraform (see Before/After above).
  4. Verify the setup. Run atmos toolchain install, then run atmos toolchain which opentofu. Confirm that atmos terraform plan <component> -s <stack> uses the expected version.
  5. Promote the version to dependencies.tools on the specific component. Do this if the version must apply only to that component's execution context, not to the whole repository as a default. See the "Default Rule" in atmos-toolchain.
  6. Remove .opentofu-version and uninstall tofuenv last. Do this only after the team verifies that atmos terraform commands resolve the correct version without it.

Command Mapping

tofuenv commandAtmos toolchain equivalent
tofuenv install 1.10.3atmos toolchain install opentofu@1.10.3
tofuenv use 1.10.3 (switches the global default in ~/.tofuenv/version)atmos toolchain set --tool-versions "$HOME/.tool-versions" opentofu 1.10.3 (writes the home-level default)
tofuenv pin (writes .opentofu-version in the current directory)atmos toolchain add opentofu@1.10.3 (adds/updates the project .tool-versions entry)
tofuenv version-nameatmos toolchain get opentofu
tofuenv list (installed versions)atmos toolchain list
tofuenv list-remote (available versions)atmos toolchain get opentofu --all
tofuenv uninstall 1.10.3atmos toolchain uninstall opentofu@1.10.3

Shell Integration

tofuenv works through shimming. Its installer adds ~/.tofuenv/bin to PATH. It typically does this with export PATH="$HOME/.tofuenv/bin:$PATH" in ~/.bashrc or ~/.zshrc. The tofu shim reads the nearest .opentofu-version file on every invocation. Plain tofu always resolves to the correct version in any shell. This needs no per-project setup.

The Atmos toolchain does not do this by default. Atmos resolves tools declared in .tool-versions (the project-wide default) or dependencies.tools (a scoped override) and injects them into PATH only for the duration of one atmos <subcommand> invocation. Plain tofu in your shell does not pick up the Atmos-managed version unless you opt in to shell integration. This is a supported mode, not a limitation. Use atmos toolchain env to export the resolved PATH into your interactive shell:

Bash (add to ~/.bashrc):

eval "$(atmos toolchain env --format=bash)"

Zsh (add to ~/.zshrc):

eval "$(atmos toolchain env --format=bash)"

Atmos has no separate --format=zsh option. The bash format emits plain POSIX export PATH=... syntax. Zsh evaluates this syntax the same way.

Fish (add to ~/.config/fish/config.fish):

atmos toolchain env --format=fish | source

PowerShell (add to $PROFILE):

Invoke-Expression (atmos toolchain env --format powershell | Out-String)

Verify with which tofu (Get-Command tofu on PowerShell). The result must point to the Atmos toolchain install directory, not the tofuenv shim.

Run atmos commands, including the shell integration commands above, from the directory that contains atmos.yaml. If your shell is in a different directory, add --chdir /path/to/project (short form -C /path/to/project) to the command.

Important: this is a static snapshot, not tofuenv's dynamic per-directory resolution. tofuenv's shim re-reads .opentofu-version on every command. Changing directory into a different project automatically switches versions. atmos toolchain env sets the resolved paths for the current directory into PATH one time, at eval time. It does not update automatically when you change directory. Re-run the eval line after you switch projects. Or, when you work across multiple projects, use atmos terraform ... instead of bare tofu. atmos terraform ... always resolves the version per invocation, regardless of shell state.

Functional Gaps

  • Partial or range-based version selectors have no equivalent today. tofuenv supports selectors similar to tfenv's selectors (latest:^1.9, latest:1.10.*) through tofuenv install arguments. Atmos toolchain version specs support exact versions, latest, pr:<n>, sha:<hex>, and ref:<branch/tag>. SemVer range constraints (~> 1.9.0, >= 1.8.0, < 2.0.0) are documented as planned, not yet implemented. If the user relies on a floating constraint, pin an exact version for now. Tell the user that range support is planned.

Cross-Links