Searching from the command line

docspack search runs the same query an agent would, and prints the results. Use it to check that a package is indexed, to see what an agent will receive, or to find something yourself.

npx docspack search "webhook signature"

An answer can also carry a declaration read from an installed library, ahead of the prose, when the question names something no documentation mentions. That path does not go through the ranking described below — see answers from the installed build.

How matching works

The index is a SQLite FTS5 table tokenized with porter unicode61. Porter stemming means a search for authentication matches a chunk that only says authenticate, and retries matches retry.

Both the chunk’s text and its tags are indexed, so a manifest that tags a chunk with idempotency makes that chunk findable even when the word never appears in the prose. Results are ranked by BM25, which favours chunks where the query terms are frequent and distinctive. Tags weigh three times as much as prose, so the chunk an author tagged for a subject beats one that merely repeats the words.

Query text is tokenized and each term is quoted before it reaches SQLite. Punctuation in a query is searched for literally instead of being interpreted as FTS syntax, so a query like auth AND (NOT "x") returns results rather than a syntax error.

Terms of one or two characters are dropped, because a question is mostly how, do, i and in, and every chunk containing one of those becomes a candidate. A query made only of short terms keeps them all, so docspack search "id db" still searches.

Narrowing and widening results

• --package <text> restricts results to packages whose name contains that text, for example --package stripe.
• --limit <n> changes how many chunks are returned. The default is 3. It works on ask and preview too, so an agent that gets three near-misses can ask again for more.
• --max-tokens <n> changes the token ceiling for the whole result set. The default is 3,000. Also honoured by ask and preview.
• --all searches every version in the index instead of only the versions this project installed. Useful when comparing releases; not what an agent should see.

Machine-readable output

Every command accepts --json, which prints the full result including chunk ids, token counts, file paths and trust flags:

npx docspack search "retry policy" --json

Exit codes

ask and search distinguish the two ways an answer can be empty, so a script does not have to read the prose to tell them apart:

Code 3 is the first-run case. The answer says which package it is, because “you have not indexed anything yet” and “the documentation does not cover this” are different problems and only one of them is yours to fix.