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.integrationis on.termhint settings set terminals.integration offremoves 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. |