Termhint Get Termhint

Runtime version manager in Termhint

Updated 19 November 2026All docs

Termhint includes a version manager for language runtimes. This page covers the supported tools, the termhint runtime commands, how a folder's version is chosen, where the files live, how every download is checked, and how to move over from nvm, pyenv, asdf and other managers. For an overview, see Runtimes. Xcode has its own page: Xcode versions and simulators.

Supported tools

Tool Name in commands Source Own version files
Node.js node (also nodejs) nodejs.org .nvmrc, .node-version
Go go (also golang) go.dev .go-version
Java java Eclipse Temurin JDKs from Adoptium .java-version
Python python CPython from python-build-standalone .python-version
Ruby ruby Precompiled builds from jdx/ruby (Apple silicon) .ruby-version
Bun bun Bun's GitHub releases .bun-version
Deno deno dl.deno.land .deno-version
Zig zig ziglang.org none
Erlang/OTP erlang Precompiled builds from erlef/otp_builds none
Elixir elixir Elixir's GitHub releases none
Gleam gleam Gleam's GitHub releases none
.NET SDK dotnet (also dotnet-core) Microsoft none
Dart SDK dart Google's Dart archive none
Julia julia julialang.org none
Xcode xcode Apple (see Xcode) .xcode-version

Tools without their own version file are pinned with .tool-versions or the global default only. The other names in the second column (nodejs, golang, dotnet-core) are asdf's; they work in commands and in .tool-versions.

Termhint installs precompiled builds only. It never compiles a runtime and never runs an install script.

Note: Ruby builds exist for Apple silicon only. Elixir runs on an installed Erlang, so install Erlang first (termhint runtime install erlang).

Install a version

termhint runtime install node              # the newest Node release
termhint runtime install node lts          # the newest long-term-support Node
termhint runtime install node 22           # the newest 22.x
termhint runtime install python 3.13       # the newest 3.13.x
termhint runtime install ruby@3.3.6        # tool and version in one word

The version can be:

A leading v is dropped (v22), and other managers' spellings work: ruby-3.3.6, temurin-21, and Elixir's 1.18.3-otp-27.

To see what you can install:

termhint runtime list-remote ruby          # releases for this Mac
termhint runtime list-remote node --all    # include pre-releases

The release list is kept for an hour. --refresh (on install and list-remote) asks the publisher again.

Elixir picks the precompiled build for the Erlang it will run on: the one your global default names, else the newest installed. If no Erlang is installed, or no build fits it, the install stops before anything is downloaded.

Choose a version

Pin a folder

termhint runtime use node 22               # this folder and the ones below it use Node 22

This writes the tool's line to .tool-versions in the current folder and keeps every other line as it was. A .tool-versions that is a symbolic link (or anything other than a regular file) is refused.

Set the default

termhint runtime use -g python 3.13        # Python 3.13 wherever nothing else is pinned

-g (or --global) writes the global defaults file, ~/.config/termhint/tool-versions. If that file is a symbolic link (for example from a dotfiles manager), the file it points to is updated.

The version does not have to be installed yet. When it is missing, the command prints the termhint runtime install line to run.

Use the system copy

termhint runtime use ruby system           # the Ruby outside Termhint, in this folder

system means Termhint leaves the tool alone, so whatever is on your PATH (Homebrew, /usr/bin) runs.

How a version is chosen

For each tool, the first answer wins:

  1. The environment variable TERMHINT_<TOOL>_VERSION, for example TERMHINT_NODE_VERSION=20.
  2. Walking up from the current folder to /, the nearest folder that has either a .tool-versions line for the tool or one of the tool's own version files (see Supported tools). Within one folder, .tool-versions comes first.
  3. The global defaults in ~/.config/termhint/tool-versions.

With no answer at all, the version set as the default is used, if there is one.

Version files are read as data:

In .nvmrc, lts/* means lts, and node or stable mean latest.

Check what a folder uses

termhint runtime current                   # this folder
termhint runtime current ~/projects/api    # another folder (its parents are searched too)

Each line shows the tool, the version asked for, the install folder (or not installed or system) and the file the version came from.

How switching works

There are no shims. On every prompt and every change of folder, Termhint's shell integration (zsh and bash) works out which version the folder asks for and puts that version's bin folder first on PATH. It also sets the variables some tools need:

Tool Variable
Go GOROOT
Java JAVA_HOME
Deno DENO_INSTALL_ROOT (its .deno/bin is on PATH too)
.NET DOTNET_ROOT
Xcode DEVELOPER_DIR

When the tool stops being active, the value from before comes back, unless something changed it meanwhile.

If a folder asks for a version that is not installed, the shell prints one line, once per folder, with the command to install it, and leaves that tool alone:

termhint: node 20 (from ~/projects/api/.nvmrc) is not installed — termhint runtime install node 20

Nothing is ever installed when you change folders.

To turn switching off in one shell, set TERMHINT_RUNTIMES_OFF=1. Editors and GUI apps that need a fixed path can use ~/.local/share/termhint/runtimes/<tool>/default, which points to your default version.

Scripts and cron jobs

Where no prompt runs, use exec. It puts the versions the current folder pins first on PATH, sets their variables and runs the command:

termhint runtime exec -- node --version
termhint runtime exec node@20 python@3.12 -- npm test

Versions named before -- win over the folder's pins. exec fails when a version it needs is not installed.

List and remove versions

termhint runtime list                      # every installed version; the default is marked (default)
termhint runtime list node                 # one tool
termhint runtime uninstall node 20.20.2
termhint runtime uninstall node 20         # works when only one 20.x is installed

When a partial version matches more than one installed version, uninstall lists them and asks you to name one.

A version folder you delete by hand drops out of termhint runtime list and Settings → Runtimes, and its record and links are removed.

Where runtimes live

What Where
Installed versions ~/.local/share/termhint/runtimes/<tool>/<version>
Version links (22, lts, latest, default) ~/.local/share/termhint/runtimes/<tool>/
Global defaults ~/.config/termhint/tool-versions
Release lists and downloads ~/.cache/termhint/runtimes

TERMHINT_RUNTIMES moves the store to another folder. XDG_DATA_HOME, XDG_CONFIG_HOME and XDG_CACHE_HOME are honored when set.

Each install folder holds .termhint-install.json, a record of the download URL, its SHA-256 and what was checked. An install is unpacked and checked in a staging folder and only then renamed into place, so a version folder that exists is complete and verified.

Verification before install

Every download is checked before anything in it runs, and each check is anchored in the publisher, not only in the server that sent the file. A missing or wrong checksum, signature or attestation is a refusal, never a warning, and there is no switch to skip it. After the checks, the new binary runs once from its folder with an empty environment (only a minimal PATH) to confirm it works.

Tool Checks
Node.js Hash in SHASUMS256.txt, which must carry a valid signature from a Node release key (built in)
Go go.dev's published hashes, plus the files as logged in Google's checksum database (sum.golang.org, pinned key), plus Google's Developer ID signature on its programs
Java Adoptium's SHA-256 plus a valid OpenPGP signature from the Adoptium release key (built in)
Python Hash in the release's SHA256SUMS plus a GitHub artifact attestation from python-build-standalone's release workflow
Ruby GitHub's recorded digest plus a GitHub artifact attestation from jdx/ruby's release workflow
Bun Hash in SHASUMS256.txt plus a Developer ID signature from Bun's Apple team on every program
Deno Published .sha256sum plus Deno Land's Developer ID signature
Zig SHA-256 from Zig's index plus a minisign signature with Zig's key (pinned)
Erlang/OTP Sigstore bundle made by erlef/otp_builds' release workflow
Elixir Published .sha256sum plus a GitHub artifact attestation from Elixir's release workflow
Gleam Published .sha256 plus a Sigstore bundle made by Gleam's release workflow
.NET SDK SHA-512 from Microsoft's release files, which must carry a valid Microsoft signature (pinned DigiCert root), plus Microsoft's Developer ID signature on the programs
Dart SDK Published .sha256sum plus a Developer ID signature from Google or FLUTTER.IO on every program
Julia SHA-256 from Julia's version list plus a GPG signature by Julia's current release key (built in)
Xcode Apple's signature on the .xip and on the app (see Xcode)

Releases that cannot pass these checks are not listed: Elixir only the 1.18 line, Bun from 1.0.24 (a few later ones are left out too), Deno from 1.38.1, Gleam from 1.10.0, Dart x64 from 2.5.0, and Julia only versions signed by its current key. A Temurin build without a published signature (before mid-2022) is refused.

The release index

For Bun, Elixir, Erlang, Gleam, Python and Ruby, Termhint first reads the list of releases from index.termhint.com, rebuilt every hour. Their own listings go through GitHub, whose API allows 60 requests an hour without a token. The list counts only when it carries a Sigstore bundle made by Termhint's index workflow, is less than a week old and is not older than the list seen before. Otherwise, and with --refresh, the publisher's own listing is used.

Only the list comes from the index. The checksums, signatures and attestations are always fetched from the publisher at install time.

A GITHUB_TOKEN in your environment raises GitHub's limit for listings that go to GitHub. It is sent only to https://api.github.com.

If an install is refused, see Troubleshooting.

Move from nvm, pyenv, asdf and others

termhint runtime migrate takes over the versions of other version managers:

termhint runtime migrate --dry-run         # what would move and which shell lines would be turned off
termhint runtime migrate nvm pyenv         # take over the named managers
termhint runtime migrate                   # take over every manager found
termhint runtime migrate --undo            # turn their shell lines back on
termhint runtime migrate --remove nvm      # also uninstall nvm and move its folders to the Trash

Managers it knows: nvm, fnm, volta, nodenv, rvm, rbenv, chruby, pyenv, goenv, jenv, sdkman, asdf, mise, bun (Bun's installer), deno (Deno's installer) and xcodes.

For each manager, migrate:

  1. Installs its versions with Termhint. An Xcode already in /Applications is kept where it is.
  2. Makes the manager's defaults your Termhint defaults.
  3. Reinstalls each version's global npm packages, gems with commands and pip tools into the matching Termhint version. Packages added with npm link are listed, not moved.
  4. Turns off the manager's lines in ~/.zshrc, ~/.zprofile, ~/.bash_profile, ~/.bashrc and ~/.profile. Each file is backed up first, and each line gets #termhint-off# in front.

A manager whose default version does not install stays on. Versions of tools Termhint does not manage (asdf's terraform, SDKMAN's gradle) are listed and stay with the manager. Bun's and Deno's installers keep their shell lines, because their bin folder holds the commands you installed with bun add -g or deno install -g.

Flag Effect
--dry-run Print the plan only
--undo Turn the lines Termhint turned off back on, byte for byte, for managers still installed. Takes no manager name and no --remove
--remove Also brew uninstall the manager (when Homebrew installed it) and move its folders to the Trash, but only once every version installed and every global package moved

Settings → Runtimes → Other Managers does the same with Replace with Termhint…. More on each manager: nvm alternative, pyenv alternative, asdf alternative.

Command reference

Command What it does
termhint runtime install <tool> [<version>] [--refresh] Download, verify and install a version
termhint runtime uninstall <tool> <version> Remove an installed version
termhint runtime list [<tool>] Installed versions
termhint runtime list-remote <tool> [--all] [--refresh] Versions the publisher offers for this Mac
termhint runtime use [-g] <tool> [<version>] Pin a version in this folder, or as the default with -g
termhint runtime current [<dir>] What a folder asks for, and whether it is installed
termhint runtime exec [<tool>@<version>…] -- <command> Run a command with the folder's versions first on PATH
termhint runtime migrate [--dry-run] [--undo] [--remove] [<manager>…] Take over other version managers

Each command prints its own help with --help. Xcode's commands are on Xcode versions and simulators; every other command is in the CLI reference.