Termhint Get Termhint

Termhint settings reference

Updated 19 November 2026All docs

Every setting of Termhint has a name like popup.font-size or prompt.folder.color. You can change it in the Settings window or with termhint settings. This page lists every key, the values it takes, its default and where it is in Settings.

The settings command

Command What it does
termhint settings Lists every setting with its value.
termhint settings list [<key-prefix>] Lists the settings, grouped, with the value, (default) when unchanged, and one line on each. A prefix like popup or prompt.folder shows only those.
termhint settings get <key> Prints only the value, on one line (for scripts).
termhint settings set <key> <value> Changes a setting.
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.
termhint settings list popup
termhint settings get popup.theme
termhint settings set popup.font-size 15
termhint settings set prompt.folder.color cyan
termhint settings reset popup

How it behaves:

Value formats

Kind Format
Switch on or off (also true/false, yes/no, 1/0).
Number A number in the range shown.
Popup color #rrggbb or #rrggbbaa.
App color #rrggbb.
Prompt color default, a color name (black, red, green, yellow, blue, magenta, cyan, white, or bright-<name>), 0–255, #rrggbb, or none for the terminal's own.
Text One argument; quote it if it has spaces. Prompt and tab-title texts take at most 40 characters.
List Comma-separated, like ls,cat.

Settings pane: Settings → Popup. Group popup: the completion popup, its look, its size and what each row shows.

Key Values Default Effect
popup.theme system, light, dark system Whether the popup is light or dark, or follows macOS.
popup.font a font family, system system The font of suggestion names, as Font Book names it ("JetBrains Mono"); system is SF Mono.
popup.font-size 10–24 13 The size of the popup's text, in points; rows grow with it.
popup.bold-matches on, off on The letters you typed show in bold in each suggestion.
popup.match-color popup color, system system The color of the letters you typed (system: the macOS accent color).
popup.text-color popup color, system system The color of suggestion names.
popup.description-color popup color, system system The color of descriptions and of plain icons.
popup.selection-color popup color, system system The highlight behind the selected suggestion.
popup.background vibrant, solid, gradient vibrant Blurred like a macOS menu, one color, or a gradient.
popup.background-color popup color #1c1c21 The solid background, and where the gradient starts (top left).
popup.gradient-color popup color #6b2b9e Where the gradient ends (bottom right).
popup.background-opacity 0.3–1 0.95 How opaque the solid or gradient background is.
popup.corner-radius 0–16 8 How round the corners are, in points.
popup.width 320–1000 440 The width in points. Below 380 rows show names only; from 680 the details sit beside the list.
popup.rows 3–20 8 How many suggestions show before the list scrolls.
popup.descriptions on, off on Each suggestion's description in its row.
popup.description-alignment column, trailing column Descriptions in one column, or against the right edge.
popup.details on, off on The selected suggestion's kind and full description, under or beside the list.
popup.hints on, off on A footer with the position in the list and the keys to use.
popup.icons on, off on An icon before each suggestion that shows its kind.
popup.colorful-icons on, off on Icons on a badge tinted by kind, rather than plain.
popup.command-names on, off on Also suggest the command itself as you type it: commands on your PATH, aliases, functions and builtins.
popup.off-for <command>,<command>,…, none none Commands the popup never opens for, also after sudo.
popup.learn runs, picks, off runs What ranks the names you use higher: lines you run, only popup picks, or nothing. off deletes what was learned.

popup.learn keeps only names Termhint knows (commands, and subcommands and options from specs), never arguments such as files, branches or hosts, in ~/Library/Application Support/Termhint/usage.json.

One pair of keys per kind of suggestion: command, option, value, script, file, folder, other. Same pane, Settings → Popup, under Icons.

Key Values Default Effect
popup.icon.<kind> symbol:<SF Symbol>, text:<1–2 characters>, image:<path>, default default The icon of that kind: an SF Symbol by name, an emoji or up to two characters, or a picture file (copied in as a small PNG).
popup.icon.<kind>.color popup color, default default The icon's color. default: the kind's own color with popup.colorful-icons, else popup.description-color.

App

Settings pane: Settings → App, except where noted. Group app: Termhint's own window.

Key Values Default Effect
app.appearance system, light, dark system Whether Termhint's window is light or dark, or follows macOS. The popup has its own: popup.theme.
app.colors rose, ocean, violet, mint, amber, graphite, custom rose The window's color preset. custom uses the three keys below.
app.accent #rrggbb #c93452 The accent of buttons, switches and the selection. Setting it picks app.colors custom.
app.glow-lead #rrggbb #dc3e6f The glow at the top left of every page. Setting it picks app.colors custom.
app.glow-trail #rrggbb #878ff4 The glow at the bottom right of every page. Setting it picks app.colors custom.
app.open-at-login on, off off Termhint opens when you log in. In Settings → Terminal → Apps. Changed through the running app.
app.accessibility granted, not granted — Read-only. Whether Termhint may use Accessibility to find the text cursor. Grant it in System Settings → Privacy & Security → Accessibility. Shown in Settings → Terminal → Apps.

If app.open-at-login says "needs approval", allow Termhint in System Settings → General → Login Items. Automatic update checks are a switch in Settings → App with no settings key; see Updates.

Terminals

Settings pane: Settings → Terminal → Apps. Group terminals: Termhint in every new terminal tab.

Key Values Default Effect
terminals.integration on, off on Autocomplete, the prompt and the colors in every new zsh tab. on: a marked block at the end of ~/.zshrc (backed up first) sources Termhint's script and puts termhint on PATH. off: the block, the script and the compiled prompt go; your choices stay. Open tabs keep what they loaded.
terminals.short-name a name, none th A shorter name to type instead of termhint. Letters, digits and . _ + -; a name already taken in a new zsh is refused. none: only termhint. New tabs get it.
terminals.zed-input on, off off The popup in Zed's terminal, through a hidden input method that Termhint.app links into ~/Library/Input Methods. It leaves your keyboard layout alone and never reads what you type.

Tab title

Settings pane: Settings → Terminal → Tab Title. Set by zsh and bash before each prompt; not inside tmux or screen. Saved in ~/.config/termhint/tab-title.json, so it stays when the integration is removed.

Key Values Default Effect
terminals.tab-title on, off off Termhint sets the tab and window title from the parts below. off gives open tabs the terminal's own title back.
terminals.tab-title.separator text — (with a space each side) What shows between two parts; empty puts them right next to each other.
terminals.tab-title.folders 0–20 0 How many trailing folders the folder part shows; 0 shows the whole path (~/… under your home folder).
terminals.tab-title.order <part id>,… folder,command,git-branch,user,host The order of the parts. Parts listed come first; the others keep their order after them.
terminals.tab-title.<part>.on on, off see below Whether the title shows this part.
terminals.tab-title.<part>.icon text empty What shows before this part, with a space between.

Parts and whether they are on by default: folder (on), command (on; only while a command runs, and only in zsh), git-branch (off), user (off), host (off).

Your own text: terminals.tab-title.text-<n>.text, .on and .icon (text-1, text-2, …). The part is made when you first set one of its keys; termhint settings reset terminals.tab-title.text-1 removes it.

Title bars use the system font: emoji and symbols show, and Nerd Font Material Design icons (U+F0000 and up) when a Nerd Font is installed; other Nerd Font icons show as a box.

Prompt

Settings pane: Settings → Terminal → Prompt. Group prompt: the theme in use, and the prompt made in Settings part by part. The part keys shape the theme custom.

Key Values Default Effect
prompt.theme off, custom, a theme id, a .json file off The prompt Termhint draws. custom: the prompt made in Settings. off: your own prompt engine draws it again. Built-in ids: agnoster, lean, pure, robbyrussell, starship.
prompt.glyphs auto, ascii, unicode, nerd auto What the prompt's symbols may use. auto: icons in terminals that show them, standard symbols elsewhere. Needs a theme in use.
prompt.transient on, off off Entered lines keep only the prompt's last line (or the theme's short form) in front. Needs a theme in use.
prompt.instant on, off off A new shell shows its first prompt at once, before the rest of ~/.zshrc runs. Adds a line at the top of ~/.zshrc. Needs a theme in use.
prompt.look text, blocks text Parts as colored text, or each on a background of its own.
prompt.edge flat, arrow, round, slant flat How a part's background ends in the blocks look. All but flat need a Nerd Font.
prompt.lines 1–3 2 How many lines the prompt has; you type on the last.
prompt.blank-line-before on, off on An empty line before each prompt.
prompt.order <part id>,… user,host,folder,git-branch,git-state,git-status,language,venv,duration,time,status,jobs The order of parts at each place. Parts listed come first; the others keep their order.
prompt.symbol text (at most 12 characters) ❯ What you type after, at the end of the last line. Empty shows none.
prompt.symbol.stand-in text ❯ What terminals without Nerd Font icons show instead of a symbol with icons.
prompt.symbol.color prompt color green The symbol's color after a command that worked.
prompt.symbol.error-color prompt color red The symbol's color after a command that failed.
prompt.symbol.bold on, off on The symbol in bold.
prompt.folders 0–20 3 How many trailing folders the folder part shows; 0 shows the whole path.
prompt.from-repository on, off on Inside a git repository, the folder starts at the repository's folder.
prompt.clock 24h, 12h 24h A 24-hour (14:03) or 12-hour (02:03 PM) clock in the time part.
prompt.clock-seconds on, off on The time part shows seconds too.
prompt.duration-from 0–86400 2 Commands that ran at least this many seconds show how long they took.
prompt.user.only-remote on, off on Show the user name only in an SSH session or as root.
prompt.host.only-remote on, off on Show the computer's name only in an SSH session.
prompt.language.languages <language>,…, none node,python,rust,go,ruby,swift,java,php,deno,bun The languages whose project version is shown.
prompt.language.icons off, emoji, nerd emoji What shows before each version.

Prompt parts

Each part has the same keys, prompt.<part>.<field>. Parts: user, host, folder, git-branch, git-state (rebase, merge, …), git-status (changed, untracked, ahead, …), language, venv (Python virtual environment), duration, time, status (exit status of a failed command), jobs (background jobs).

Field Values Effect
on on, off Whether the prompt shows this part.
place 1, 2, 3, right On the left of line 1, 2 or 3, or at the right end of the first line. A line past prompt.lines means the last line. Default 1 for every part.
color prompt color Its text in the text look; its background in the blocks look (none: blue there).
text-color prompt color Its text on its background, blocks look only. Default none (black).
bold on, off In bold.
italic on, off In italics. Default off.
underline on, off Underlined. Default off.
word-before text A word before it in the terminal's own color, like on (text look only).
word-after text A word after it in the terminal's own color, like in (text look only).
prefix text Text right before it in its color: an icon, a bracket.
suffix text Text right after it in its color.

Defaults that differ by part (other text fields are empty, bold is off):

Part on color bold Other
user on yellow on word-after in
host on green on word-after in
folder on cyan on
git-branch on magenta on word-before on
git-state on yellow on prefix (, suffix )
git-status on red on prefix [, suffix ]
language on green on word-before via
venv on yellow off prefix (, suffix )
duration on yellow on word-before took
time off bright-black off word-before at
status off red on prefix ✘
jobs off blue on prefix ✦

Your own text in the prompt: set prompt.text-1.text (text-2, … for more). The part is made at the end of the first line when you first set it, takes the same fields as the parts above plus text, and termhint settings reset prompt.text-1 removes it.

termhint settings set prompt.text-1.text "on call"
termhint settings set prompt.text-1.color red

Colors

Settings pane: Settings → Terminal → Colors, except colors.native.*, which are in Settings → Terminal → Apps. Group colors: the scheme in use, and the scheme made in Settings.

Key Values Default Effect
colors.scheme off, custom, a scheme id, a .json file off The colors your terminals show (background, text and 16 colors). off: each terminal's own. custom: the scheme made in Settings. Open tabs switch at once.
colors.light-scheme none, a scheme id, a .json file none The scheme used while macOS is light; colors.scheme is then used while it is dark.
colors.lists on, off off File lists (ls, completion lists) in the scheme's colors where nothing else colors them.
colors.syntax on, off off The command line being typed in the scheme's colors (zsh-syntax-highlighting, zsh-autosuggestions).
colors.native.<terminal> on, off off The colors in that terminal's own config too, so its windows open in them before a shell starts. One marked block, backed up first; off gives the file back. Terminals: ghostty, kitty, wezterm, alacritty.

colors.light-scheme, colors.lists, colors.syntax and colors.native.* need a scheme in use.

The custom scheme

These keys edit the scheme made in Settings. Before there is one, the first edit starts from a copy of the scheme in use, else of One Dark. They have no default; set a value.

Key Values Effect
colors.custom a scheme id, a .json file Starts the custom scheme again from a copy of that scheme ("Start from" in Settings). Every color is replaced; its name stays Custom.
colors.custom.background #rrggbb The window's background.
colors.custom.foreground #rrggbb The text's color.
colors.custom.cursor #rrggbb, none The cursor's color.
colors.custom.cursor-text #rrggbb, none The character under the cursor.
colors.custom.selection-background #rrggbb, none The background of selected text.
colors.custom.selection-foreground #rrggbb, none The color of selected text.
colors.custom.<color> #rrggbb The 16 terminal colors: black, red, green, yellow, blue, magenta, cyan, white, and bright- of each.

none means the terminal's own.

Command-line highlighting

Used with colors.syntax on. Values: a color name (black … white, bright-<name>, which follow the scheme's colors), #rrggbb, or default (the usual color for it). Default: default.

Key What it colors
colors.custom.syntax.command Commands: programs, builtins, functions, aliases.
colors.custom.syntax.keyword Shell words like if, for and do.
colors.custom.syntax.string Quoted text.
colors.custom.syntax.variable $name and $(…) inside double quotes.
colors.custom.syntax.option Options like -x and --long.
colors.custom.syntax.comment Comments.
colors.custom.syntax.error A command that does not exist.
colors.custom.syntax.glob Patterns like *.txt and history words like !!.
colors.custom.syntax.operator ;, |, && and redirections.
colors.custom.syntax.suggestion The suggested rest of the line (zsh-autosuggestions).

See Terminal colors, Prompt themes, Tab titles and The menu bar and Settings.