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:
- A change applies at once. The running app and the open shells are told; the output says what changed and what follows ("open shells asked to switch: 3").
- Termhint.app does not need to be running, except for
app.open-at-loginandapp.accessibility, which are asked of the running app. - The value is checked first. An invalid one exits with status
1and lists the values allowed. An unknown key exits with1and names close ones. resetwith a prefix skipsapp.open-at-login; reset it by name. Keys without a default (thecolors.custom.*colors) can only be set.- Keys are not case-sensitive.
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. |
Popup
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.
Popup icons
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.