Termhint Get Termhint

Termhint CLI reference

Updated 19 November 2026All docs

The termhint command sets up your shells, chooses the prompt theme and the terminal colors, manages Nerd Font icons and language versions, and changes every setting of the app. This page lists every command, its arguments and its flags.

Getting help

termhint alone prints the overview. Every command has its own help page:

termhint help colors set
termhint colors set --help
termhint colors set -h

termhint help <command>… takes a command and its subcommands. For runtime and xcode commands, the help comes from the runtime helper, which runs those commands.

The short name th

The shell integration puts termhint on your PATH, plus a short name next to it: th by default. th theme set pure is the same as termhint theme set pure, and the popup completes th like termhint.

Change or remove it with the terminals.short-name setting, or in Settings → Terminal → Apps:

termhint settings set terminals.short-name t
termhint settings set terminals.short-name none

The name takes letters, digits and . _ + -. A name that a command, alias, function or shell builtin already has in a new zsh is refused, because that one would run instead. New tabs get the new name. If termhint install finds the short name taken, it tells you and suggests picking another.

Exit status

Status When
0 The command worked.
1 A wrong call (the usage lines are printed), a failed command, an invalid setting value, an unknown setting, or Termhint is locked after the trial.
1 uninstall --all: one of its steps failed (the other steps still run).
1 runtime migrate: a removal failed or a global package was not moved.
Its own runtime … and xcode … exit with the runtime helper's status.

Errors go to standard error, prefixed with the name you typed (termhint: or th:).

Commands while locked

After the 7-day trial, Termhint needs a license. Until you enter one, the popup and prompt themes are off and most commands stop with exit status 1. These still run, so you can always get out or pay:

Command Runs while locked
termhint license … Yes
termhint uninstall … Yes, also --all
termhint runtime exec … Yes; runtimes you installed keep working
termhint colors off, colors reset, colors native off … Yes
termhint icons off …, icons remove …, icons font off …, icons font none Yes
termhint help …, --help, -h Yes
Everything else No

See License and Troubleshooting.

install

termhint install [zsh|bash]

Installs the shell integration. zsh when no shell is named.

Shell What it does
zsh Writes ~/.config/termhint/shell/termhint.zsh and adds one marked block at the end of ~/.zshrc (backed up first) that loads it in every new shell. The block also puts termhint on PATH. Autocomplete, prompt themes, terminal colors and runtime versions.
bash Writes termhint.bash, sourced from the end of ~/.bashrc and of the login file (login shells read that instead). Prompt themes, terminal colors and runtime versions; no autocomplete.

The prompt theme and colors you chose earlier are compiled again. Open a new terminal tab to load it. Termhint.app installs the zsh block itself at launch unless terminals.integration is off. See Install.

uninstall

termhint uninstall [zsh|bash]
termhint uninstall --all
Form What it does
uninstall [zsh|bash] Removes the marked block from the rc file (backed up first), the script and the compiled theme. zsh when no shell is named. Open tabs keep it until they close.
uninstall --all Before you remove the app: undoes every change Termhint made outside its own folders. One line per step; a failed step does not stop the others and makes the exit status 1.

--all takes the colors out of each terminal's own config, puts back the icon and font settings Termhint changed in a terminal, removes the zsh blocks (with the --instant one) and the bash block, removes the PATH links, turns terminals.integration and terminals.zed-input off, and deletes what the popup learned (popup.learn). Your settings, runtimes, fonts and the license keychain item stay; the end of the output lists them.

Note: Termhint.app adds the zsh block back at its next launch while terminals.integration is on. termhint settings set terminals.integration off removes it and keeps it off.

See Uninstall.

license

Command What it does
termhint license Same as license status.
termhint license status Days left in the trial, or the license (its key masked) and when Polar last confirmed it.
termhint license open Opens Settings → License (starts Termhint.app if it is not running).

The app holds the license in your keychain, so the command asks the app. You enter a key in Settings → License, never on the command line, where it would land in your shell history. See License.

settings

Command What it does
termhint settings Lists every setting with its value.
termhint settings list [<key-prefix>] Lists the settings with their values, (default) when unchanged, and one line on each. A prefix like popup or prompt.folder shows only those.
termhint settings get <key> Prints one value on one line, for scripts.
termhint settings set <key> <value> Checks the value, saves it, and says what changed.
termhint settings set <key> --help Explains one setting and the values it takes.
termhint settings reset <key> Puts a setting, or every setting under a prefix, back to its default. reset prompt.text-1 removes that text part.
termhint settings list popup
termhint settings set popup.font-size 15
termhint settings reset prompt.folder

Every key, its values and its default: Settings reference.

theme

Prompt themes: Termhint draws the prompt from a theme file (JSON, never executed). Needs the shell integration. Your own themes go in ~/.config/termhint/themes/<name>.json; the prompt made in Settings is the theme custom.

Command What it does
termhint theme list Shows the built-in themes and your own (* = in use), then the glyph level in use.
termhint theme set <theme> [options] Lets Termhint draw the prompt with this theme (a name or a .json file). Open shells switch at once. Options you leave out stay as they were.
termhint theme off Gives the prompt back to your shell setup (Starship, oh-my-zsh, …). Open shells switch at once.
termhint theme preview [<theme>] [--glyphs <level>] Prints how a theme looks with made-up values; every theme when none is named. Changes nothing.

Options of theme set:

Option What it does
--glyphs auto|ascii|unicode|nerd What your terminal font can show. auto: icons in terminals that show them, standard symbols elsewhere. ascii: letters, digits and punctuation. unicode: symbols every modern font has. nerd: Nerd Font icons. Default auto, or as chosen before.
--transient Once a line is entered, only the prompt's last line (or the theme's short form) stays in front of it.
--no-transient Keep the whole prompt in front of entered lines.
--instant A new shell shows its first prompt at once, before the rest of ~/.zshrc runs. Adds a second marked block at the top of ~/.zshrc (backed up first).
--no-instant Wait for ~/.zshrc again before the first prompt.
termhint theme set lean --glyphs nerd
termhint theme set pure --transient
termhint theme set ~/my-theme.json

See Prompt themes.

colors

Terminal colors: every shell colors its own terminal with escape sequences, so no terminal setting changes (not inside tmux or screen). Needs the shell integration. Your own schemes go in ~/.config/termhint/colors/<name>.json; the scheme made in Settings is custom.

Command What it does
termhint colors list Shows the schemes with their appearance (dark or light) (* = in use), then what is in use.
termhint colors set <scheme> [options] Colors your terminals' shells with this scheme. Open tabs switch at once, new ones when their shell starts.
termhint colors native [off] <terminal> Also puts the colors into a terminal's own config (one marked block, backed up first), so its windows open in them. off gives the file back as it was. Needs a scheme in use.
termhint colors preview <scheme> Colors this window only, until colors reset or it closes.
termhint colors reset Ends a preview: this window goes back to the scheme in use or its own colors.
termhint colors off Gives each terminal its own colors back.

<terminal> for native: ghostty, kitty, wezterm, alacritty, or all (those found on this Mac; with off, every one).

Options of colors set (--lists and --syntax stay until turned off; options you leave out stay as they were):

Option What it does
--light <scheme> Use this scheme while macOS is light, and <scheme> while it is dark.
--lists Also color file lists (ls, completion lists) where nothing else does.
--no-lists Stop coloring file lists.
--syntax Also set the colors zsh-syntax-highlighting and zsh-autosuggestions use on the command line.
--no-syntax Stop coloring the command line's highlighting.
termhint colors set dracula --light solarized-light
termhint colors native ghostty
termhint colors native off all

See Terminal colors.

icons

Nerd Font icons in the prompt where a terminal shows them. termhint icons alone prints the status of every terminal.

Command What it does
termhint icons / icons status The Nerd Fonts on this Mac and each terminal's status.
termhint icons fonts [--refresh] The font families of the newest Nerd Fonts release. --refresh asks GitHub again instead of the 1-hour cache.
termhint icons install [<font>] Downloads a Nerd Font, checks it against the release's SHA-256 list and installs its single-width (Mono) faces into ~/Library/Fonts. Default NerdFontsSymbolsOnly (the icons alone).
termhint icons remove <font> Deletes the files of a font Termhint installed.
termhint icons setup icons on for every terminal that doesn't show icons yet, except those turned off with icons off. iTerm2 and Tabby are skipped while they run.
termhint icons on <terminal> Makes a terminal show icons (installs the icons font first when no Nerd Font is there).
termhint icons off <terminal> Puts back what icons on changed; a terminal that shows icons by itself is switched to standard symbols until icons on.
termhint icons font [<family>|none] Without a family: the chosen font and the installed Nerd Fonts with letters. With one: chooses it (none clears it) and sets it again in every terminal whose font switch is on.
termhint icons font on <terminal> Sets the chosen font in a terminal.
termhint icons font off <terminal> Puts back the font the terminal used before.
termhint icons test Prints a few icons here and says what Termhint knows about this terminal.

<terminal>: terminal, ghostty, kitty, wezterm, rio, kaku, cmux, cursor, vscode, vscode-insiders, vscodium, windsurf, kiro, trae, positron, iterm2, alacritty, hyper, tabby.

termhint icons on cursor
termhint icons font JetBrainsMono Nerd Font Mono
termhint icons font on ghostty

See Terminal icons for what changes in each terminal.

runtime

Language versions: Node.js, Go, Java, Python, Ruby, Bun, Deno, Zig, Erlang, Elixir, Gleam, .NET, Dart, Julia and Xcode. Every command but migrate runs in Termhint's runtime helper.

Command What it does
termhint runtime install <tool> [<version>] [--refresh] [--from <path>] Downloads, verifies and installs a version. Nothing is installed when a check fails.
termhint runtime uninstall <tool> [<version>] Removes an installed version.
termhint runtime list [<tool>] Installed versions, all tools or one.
termhint runtime list-remote <tool> [--all] [--refresh] Versions the publisher offers for this Mac.
termhint runtime use [-g|--global] <tool> [<version>] Pins a version in this folder's .tool-versions, or with -g as the default everywhere nothing else is pinned.
termhint runtime current [<dir>] What this folder (or <dir>, and its parents) asks for, and whether it is installed.
termhint runtime exec [<tool@version>…] -- <command> [<args>…] Runs a command with this folder's versions first on PATH. Versions named before -- win over the pins.
termhint runtime migrate [<manager>…] [options] Takes over other version managers' versions and turns them off.
termhint runtime --version The runtime helper's version.

Arguments and flags:

Argument or flag Meaning
<tool> A tool, or tool and version in one word (node, ruby@3.3). asdf's names nodejs, golang and dotnet-core work too.
<version> 22, 22.11.0, lts or latest (the default). A partial version means the newest release that starts with it; pre-releases only when named. A leading v is dropped, and other managers' spellings work (ruby-3.3.6, temurin-21). Node also takes lts-<name> or lts/<name>. use also takes system (the tool installed outside Termhint).
--refresh Ask the publisher for its release list again instead of the 1-hour cache.
--from <path> Xcode only: install from a .xip, or adopt an Xcode .app where it is.
--all list-remote: include pre-releases.
-g, --global use: set the default instead of this folder's version.

Options of runtime migrate:

Option What it does
<manager>… nvm, fnm, volta, nodenv, rvm, rbenv, chruby, pyenv, goenv, jenv, sdkman, asdf, mise, bun, deno, xcodes. Every one found when none is named.
--dry-run Only print the plan.
--undo Turn the lines Termhint turned off back on, byte for byte, for managers still installed.
--remove Also brew uninstall the managers and move their folders to the Trash, only once every version installed and every global package moved.

migrate installs their versions, makes their defaults the global ones, reinstalls each version's global npm packages, gems with commands and pip tools, then turns off their lines in ~/.zshrc, ~/.zprofile, ~/.bash_profile, ~/.bashrc and ~/.profile (backed up first; each gets #termhint-off# in front).

termhint runtime install node 22
termhint runtime use -g python 3.13
termhint runtime exec node@20 python@3.12 -- npm test
termhint runtime migrate --dry-run

See Runtimes.

xcode

Xcode's own steps. Install Xcode versions with termhint runtime install xcode; sign in to Apple in Settings → Runtimes.

Command What it does
termhint xcode select <version> Makes this Xcode the default: pins it for the shell and runs xcode-select -s (asks for an administrator).
termhint xcode first-launch <version> Accepts the license and runs the first launch (asks for an administrator).
termhint xcode platforms [<version>] Installed simulator runtimes and the platforms to download.
termhint xcode platform install <name> [--xcode <version>] Downloads a simulator platform (iOS, watchOS, tvOS, visionOS) with xcodebuild -downloadPlatform.
termhint xcode platform remove <id> Removes an installed simulator runtime by the identifier xcode platforms prints.
termhint xcode session status [--check] Whether an Apple developer session is stored; --check also asks Apple whether it still accepts it.
termhint xcode session clear Removes the stored session from the Keychain.

<version> is an installed Xcode such as 16.2 or 16.3-beta.2 (see termhint runtime list xcode). See Xcode.

help

termhint help [<command>…]

Shows the help of a command, like termhint help colors set. termhint <command> --help (or -h) prints the same; termhint alone prints the overview.

complete

termhint complete <text-before-cursor> [<text-after-cursor>] [--specs <dir>]

Prints the suggestions the popup would show, one per line: its kind, a tab, its name and its description. Useful to check what Termhint knows about a command. Not listed in the help.

termhint complete "git ch"

Debugging commands

These run but are hidden from the help and from completion. You do not need them in daily use.

Command What it does
termhint spec Prints termhint's own completion spec (JSON); exits with 1 and prints nothing when the runtime helper cannot give its part.
termhint preview [--specs <dir>] [--show-buffer] Prints the popup as text for the open shells instead of drawing it. Only one of Termhint.app, listen and preview can be attached at a time. Ctrl-C ends it.
termhint listen [--show-buffer] Prints what the open shells send. Command lines show as byte counts unless --show-buffer is given. Ctrl-C ends it and prints latency stats.
termhint hook zsh|bash Prints a shell integration script.
termhint dir Prints the folder in which shells and the app exchange messages.
termhint replace <pid> <expect-left> <expect-right> <new-left> <new-right> Asks a shell to replace its command line, only if it still matches.