CLI

All commands resolve chops-search.toml by walking up from the current directory, and per-command flags override its values for that run. A global --site <DIR> starts the walk somewhere else, useful from a repo root or in CI.

chops-search init

Scaffold a site's integration: chops-search.toml, content/search.md, and .gitignore entries, then print the template snippet for a site-wide search box. Nothing is ever overwritten; re-running reports what it skipped.

chops-search model fetch [REPO]

Download the embedding model and record what landed in .chops-search/model.lock.json. The only command that touches the network. REPO is a HuggingFace repo, default minishlab/potion-base-8M; any model2vec model works, the listed ones are tested.

chops-search model verify

Re-hash the model directory against the lockfile; non-zero exit on mismatch. No network.

chops-search build

Read the content tree and the model, write hashed artifacts plus the wasm engine, worker, page script, and stylesheet into the output directory. The BM25F field weights and the scoring calibration from chops-search.toml are written into index.bin, so the browser scores with what the site configured; the build log's scoring: line states what shipped.

chops-search docs

Print every indexed document with its URL and chunk count. Run it after adding a post; these URLs are what eval expectations must match.

chops-search query <QUERY>

Explain a ranking: how the query tokenized on both sides, per-term keyword scores with document frequencies and per-field term frequencies, best-chunk cosine per document, and each engine's contribution to the fused order. Calls the same scoring code as the ranker, so it cannot drift. The scoring flags exist for diagnosis: they override what index.bin baked, for this run only.

chops-search eval

Run a labelled query set through the real engine over the real byte path (plan, range-fetch, ingest, search) and report recall@1 and recall@3 by kind, plus real bytes-per-query. Baked values from index.bin are the defaults; every scoring flag overrides for the run, which is how sweeping works without a rebuild.

Sweep mode. With either sweep flag the case set runs once per point of the k × alpha grid and prints recall per cell instead of per-case lines; every other scoring flag acts as the fixed base for every cell, and the best cell is re-run for its per-kind breakdown and failure list. --fail-under is ignored, since half the grid is supposed to be worse than the baseline; that's what a sweep is.

chops-search plan [QUERY]

The network-cost instrument. Without a QUERY, it runs the gate query set and prints, per (prefix, gap) cell, the eager payload every visitor downloads against the per-query cost: prefix hit rate by rows, the share of queries that fetch nothing, bytes and requests per query with their maxima, and dead bytes (rows fetched only because coalescing merged across a gap). A coverage: line states the prefix size that would cover 50, 90, 99, and 100 percent of the rows the fixture needs, and two tables name the rows outside the prefix and the costliest cases, so a surprising mean can be traced to a line.

With a QUERY, it prints the detail: each token's row, whether it lives in the prefix or in a range, the coalesced ranges as inclusive byte spans, and the total against the rows file.

Prefix sizes and gaps are simulated from the frequency-ordered row ids, so no rebuild is needed; the simulator is checked against the engine's own planner at the shipped cell over every case before anything prints, and a mismatch is a hard error.

The --curl output is verified by the server, not by the tool: every line should read 206 with a byte count equal to the span's length. A 200 means the host ignored the Range header, which is the condition the worker detects and degrades from.

chops-search plan
chops-search plan --prefix-rows 256,512,1024,2048
chops-search plan "content security policy" --curl https://your.site/search | sh

chops-search calibrate

Walk each scoring knob one value at a time against the gate query set and report, per knob, whether the current value should stay. Every cell is one full eval pass with exactly one field changed from the baked base, diffed against the baseline case by case: totals are never compared, since a +2/-2 wash prints as zero. Under each row of the table the moved cases are named, + and - for recall@1, +3 and -3 for recall@3, so a case that fell off the podium shows on two lines; only recall@1 movement can nominate a value.

Verdicts are nominations, never edits. keep <value> states the plateau the current value sits on and the nearest measured cliff on each side; an axis edge is reported as unmeasured beyond, not as safe. REVIEW <value> means a cell gained at least two cases at recall@1 net of losses: the printout names every gained and lost case, re-runs the candidate against the known-failures fixture and names casualties there, and ends at "explain each flip before pinning". A named casualty blocks promotion. This command never writes chops-search.toml.

Expect keep on nearly every knob. That is the calibration holding, not the tool failing, and it is the point: permission to stop turning knobs and go work on the corpus or the fixtures instead.

strong_cos is not walked: it disables at infinity, so a linear axis has no honest cell for "off". rrf_k and rrf_alpha walk separately but are coupled; a candidate on either is a pointer at the joint eval --sweep-rrf-k --sweep-rrf-alpha grid, not a value to pin from a one-dimensional table. rrf_k and kw_floor have no config key, and a candidate on them says so. min_cos has one, but pinning it changes the kind of value: unset derives the floor from dims, set freezes it across a future dims change, and a min_cos nomination carries that note.

For a finer axis, generate it in the shell:

chops-search calibrate --knob min_cos --values (seq 0.27 0.01 0.34 | string join ,)

chops-search completions <SHELL>

Emit a conventional static completion script. Prefer the dynamic path, which computes candidates at completion time. Hidden from --help; it still works.