CLI Reference

🚩 CLI Reference

nerd-fonts-installer [flags]

No subcommands. Flags accept both -flag and --flag.

---

Flags

--config <path>

Use a specific config file instead of discovering one.

nerd-fonts-installer --config ./fonts.yaml

Takes priority over NERD_FONTS_INSTALLER_CONFIG and over every discovery path. A missing or invalid file is an error — the tool will not silently fall back to discovery.

---

--dry-run

Print exactly what would happen, then exit. Nothing is downloaded and nothing is written.

nerd-fonts-installer --dry-run

• Would install JetBrainsMono from https://…/JetBrainsMono.zip into /home/dev/.local/share/fonts/NerdFonts/JetBrainsMono
• Would install Hack from https://…/Hack.zip into /home/dev/.local/share/fonts/NerdFonts/Hack
↻ Would refresh font cache for /home/dev/.local/share/fonts/NerdFonts

Use it as a config linter: it parses, validates, and resolves the release first.

---

--font-names

Print YAML-ready family names for the selected release, then exit.

nerd-fonts-installer --font-names

# v3.4.0
families:
  - 0xProto
  - 3270
  - AdwaitaMono
  …

The release comes from your config if one is found or passed, otherwise latest. To list a specific release's families, pin it in a config and point at it:

nerd-fonts-installer --config ./pinned.yaml --font-names

Pipe it around like any other output:

nerd-fonts-installer --font-names | grep -i mono

---

--interactive

Open the terminal picker when no config file is found.

nerd-fonts-installer --interactive

If a config is found, it is used and the picker never appears — the flag is a fallback, not an override. Requires a real terminal on both stdin and stdout; in a pipe or CI it exits 2 rather than hanging.

See 🖱️ Interactive Picker for keybindings.

---

--icons <mode>

Choose the icon set used by the picker.

Mode	Use when
auto (default)	Always safe — never requires patched glyphs.
nerd	You already have a Nerd Font active in this terminal.
unicode	You want symbols but not Nerd Font glyphs.
ascii	Plain terminals, serial consoles, minimal SSH sessions.

nerd-fonts-installer --interactive --icons nerd
nerd-fonts-installer --interactive --icons ascii

An unknown mode is a user error and exits 2.

---

--version

Print version, commit, and build date, then exit.

nerd-fonts-installer --version

Source builds report dev — the real values are injected by the release workflow.

---

🌍 Environment variables

Variable	Effect
NERD_FONTS_INSTALLER_CONFIG	Config path. Ranks just below --config, above all discovery paths, and applies to --font-names as well.
XDG_CONFIG_HOME	Searched during discovery when set to an absolute path.
HOME	Expands ~ in destination; also the base for ~/.config.

---

🔢 Exit codes

The codes are a stable contract — scripts can branch on them.

Code	Meaning	Examples
0	Success, or the user cancelled the picker	Install finished; you pressed q
1	Runtime failure	Network error, disk full, extraction failure, checksum mismatch
2	Input you can correct	No config found, unknown release tag, bad --icons value, invalid flag

if ! nerd-fonts-installer --dry-run; then
  case $? in
    2) echo "fix your config" ;;
    *) echo "something broke" ;;
  esac
fi

Note

Cancelling the picker exits 0 on purpose — deciding not to install anything is not a failure, and a bootstrap script under set -e should not abort.

---

📤 Output streams

Stream	Carries
stdout	The things you might pipe: --font-names output, --dry-run plan, --version.
stderr	Progress and diagnostics: "Using config …", install progress, warnings, errors.

That split means nerd-fonts-installer --font-names > families.yaml gives you a clean file while you still see progress on screen.

---

Next: 🍳 Recipes · 🩹 Troubleshooting