nrepo search

nrepo search <query> [options]

Runs a semantic search: the query is embedded, matched against your idea vectors, filtered by a minimum score, and reranked. Archived ideas are excluded.

Options

Flag	Type	Default	Description
--limit <n>	number	20	Maximum results. Values above 100 are clamped to 100.
--json	boolean	false	Output as JSON.
--human	boolean	—	Force human-readable output. Wins over --json.

Output

nrepo search "authentication flow"

Search: "authentication flow" (semantic) — 3 results

#42 exploring  ⬡ Rewrite auth flow [auth, security] (92%)
#18 captured   ◎ Session cookie cleanup [auth] (78%)
#7  shipped    ◈ Login redirect bug (65%)

The header names the search type that actually ran — semantic or fts. Each row is the standard idea line: number, status, source glyph, title, tags, and the match score as a percentage.

nrepo search "authentication flow" --json

{
  "query": "authentication flow",
  "results": [
    { "id": 391, "number": 42, "title": "Rewrite auth flow", "status": "exploring", "score": 0.92, "tags": ["auth", "security"] }
  ],
  "search_type": "semantic"
}

Caution

--json returns an object, not an array. Pipe through .results: nrepo search "auth" --json | jq -r '.results[].title'.

When it returns nothing

Caution

A semantic search that finds no match above the score threshold returns an empty result set. It does not fall back to keyword search. The agent and the MCP server do fall back; the CLI and the REST API do not, so “no results” from nrepo search does not mean the words appear nowhere in your repo.

Two common causes:

• The idea is too new. Embeddings are generated on a queue after capture. An idea pushed seconds ago has no vector yet and cannot be found semantically. nrepo log --limit 5 will still show it.
• The wording is too distant. Semantic matching is not substring matching. For a literal term — an error code, a package name — use nrepo log and filter, or search from the web app, which exposes a keyword mode the CLI has no flag for.

Free plan

The free plan includes 10 semantic searches per calendar month. Past that the server runs keyword (FTS) search instead and says so in the response:

Search: "authentication flow" (fts) — 2 results

In --json, the same case adds semantic_limit_reached: true and a semantic_limit_message. Keyword results carry "score": null, so the human rows show no percentage. The counter resets at the start of each month.

Next Steps

Search How semantic search is built, what the score threshold means, and which surfaces fall back to keyword.

nrepo log List ideas by status or tag when you know exactly what you are looking for.

nrepo show Open a result in full, with its body, links, and relations.

nrepo graph Walk outward from a result through its connections.