findnerd 0.1.0

Semantic search for Nerd Font glyphs
findnerd-0.1.0 is not a library.

findnerd

Fast, offline search for Nerd Fonts glyphs from your terminal.

findnerd searches a bundled glyph catalog by concept, name, label, alias, category, glyph, or Unicode codepoint. It combines semantic retrieval, SQLite FTS5, and typo-tolerant matching, with both an interactive terminal UI and machine-readable one-shot output. The glyph catalog is embedded in the binary; the semantic model is fetched once on first run (or embedded too, with the embed-model feature), after which searches are fully offline.

Features

  • Interactive search with live previews and keyboard or mouse navigation
  • Hybrid ranking across semantic, full-text, and fuzzy-name results
  • Dedicated semantic, BM25, and fuzzy matching modes
  • Filters and category include/exclude controls
  • Structured JSON output for scripts
  • Fully local catalog; embedding model cached after a one-time download

Requirements

  • A terminal configured with a Nerd Font to render glyphs
  • Rust 1.94 or newer when building from source

Install

From crates.io:

cargo install findnerd

On first run, findnerd downloads the pinned potion-base-8M model (~29 MB, checksum-verified) into the user cache directory and reuses it thereafter.

For a fully offline, self-contained binary, download a prebuilt release from GitHub Releases, or build with the model embedded from a git checkout:

git clone https://github.com/can1357/findnerd.git
cd findnerd
cargo install --path . --no-default-features --features embed-model

Usage

Run without a query to open the interactive UI:

findnerd

Pass query words for one-shot output:

findnerd rust crab
findnerd terminal --semantic --limit 10
findnerd git --category oct --json

Force the interactive UI with an initial query:

findnerd --interactive folder

Interactive controls

Key Action
Type Edit the search query
Up / Down or mouse Move through results
Enter or double-click Select a glyph and exit
Ctrl-Y Copy the selected glyph through OSC 52
Tab / F2 Cycle ranking mode
Shift-Tab Cycle ranking mode backward
F3 / Ctrl-G Cycle category
Esc Clear the query, then quit
Ctrl-C / Ctrl-Q Quit

Ranking modes

Hybrid ranking is the default.

Option Ranking
none Reciprocal-rank fusion over all three strategies
--semantic Dense semantic-vector similarity
--bm25 SQLite FTS5 BM25 over names, labels, and aliases
--match Typo-tolerant fuzzy matching over icon names

Filters

Repeat --filter to combine constraints. Prefix an expression with ! to negate it.

findnerd cloud --filter label:rain
findnerd folder --filter '!category:weather'
findnerd --query '' --filter code:U+E7A8

Supported fields are name, label, alias, category, glyph, and code. The aliases aliases, cat, codepoint, and unicode are also accepted. A filter without a field searches all text metadata.

Restrict a search to one or more category slugs:

findnerd git --category oct,dev
findnerd git --oct --no-dev
findnerd --list-categories

Included categories are combined with OR. Exclusions take precedence.

JSON output

Use --json for structured results containing glyph metadata, category details, codepoints, aliases, and normalized scores:

findnerd branch --category oct --limit 5 --json

One-shot searches exit with status 0 when results are found, 1 when no results match, and 2 on an error.

Development

cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo run -- rust