CLI reference
dither search
Search across your entries.
dither search <query> [flags]Searches the qmd index built from your configured library. Refuses with the standard pre-init error until dither init has run.
Output depends on where it lands. On a TTY: an aligned table of score docid collection title. Piped: one tab-separated line per hit — <docid>\t<score>\t<collection>\t<path>\t<title> (with --preview, each snippet line is appended as a sixth column on its own row). The docid is the key dither get takes.
Arguments
| Name | Description |
|---|---|
query | Positional. The search string. Required. |
Flags
| Flag | Description |
|---|---|
-c, --collection <name> | Restrict the search to a single collection (one top-level folder under the library). |
-n, --limit <N> | Max results to return. Defaults to qmd's internal default. |
--rerank | Run the LLM reranker over the candidate set. Slower, higher quality. Only meaningful in hybrid mode. |
--mode <hybrid|lex> | hybrid (default) combines BM25 + vector + LLM query expansion. lex is pure BM25 — no models, no embeddings, instant. |
-p, --preview | Show a snippet of the matched line under each hit. |
-A, --after <N> | Preview N lines after the match (grep -A). Implies --preview. |
-B, --before <N> | Preview N lines before the match (grep -B). Implies --preview. |
-C, --context <N> | Preview N lines around the match (grep -C). Implies --preview; -A/-B override their side. |
--mode only accepts the literal strings hybrid and lex; anything else is ignored and the default is used.
Examples
Search everything:
dither search "auth flow"
# 0.842 a1b2c3d4 notes Auth flow notes
# 0.611 e5f6a7b8 meetings Q3 planningRestrict to one collection, top 5:
dither search "auth flow" -c notes -n 5Lexical-only (no model download required):
dither search "exact phrase" --mode lexWith reranking:
dither search "what did I write about auth" --rerankWith two lines of context around each match:
dither search "auth flow" -C 2Notes
- Hybrid mode requires qmd's models. By default,
dither initpre-downloads them so the first query is fast; pass--no-downloadat init to skip and let them lazy-load instead. - If the library is empty,
searchreturns no results silently. - While an embedding pass is still running, search prints a note that some results may be missing — re-run once it finishes.
- Make sure the index is current — run
dither index updateafter editing files outside the plugin runner.
See also: CLI overview.