Command search

Command: search

Natural-language semantic search across code and durable knowledge.

Synopsis

columbus search <query> [flags]

Description

The query is embedded on-device and matched by vector similarity (k-nearest neighbors over the vec0 store), then re-ranked by deterministic heuristics — finding results by meaning, not just exact words. When no onnxruntime runtime is available it degrades to keyword (FTS) ranking; columbus doctor shows which.

Results span code, free-form memory, and the epic → story → task hierarchy. Every hit carries a score and a human-readable why (semantic match for vector hits, or a heuristic reason). Search is locate-first: by default it returns locations, signatures and scores — add --snippets for code bodies. For usage patterns see Searching Effectively.

Flags

Flag	Default	Description
--kind string	all	What to search: code|memory|epic|task|all
--limit int	15	Maximum number of results (global flag)
--context-lines int	3	Lines of context around matched ranges
--snippets	off	Attach code bodies inline
--snippet-lines int	0	Cap snippet length in lines (0 = default 60)

Plus global flags (--json, --llm, --no-color). For the dependency graph, see Command: graphs.

Examples

$ columbus search "how are credentials checked"
1. Check  [method]  (score 0.51, semantic match)
   internal/auth/auth.go:9
2. Authenticator  [class]  (score 0.46, semantic match)
   internal/auth/auth.go:6
...

$ columbus search "token validation" --kind all --limit 5
# code symbols + any matching epics/stories/tasks/memories, ranked together

--json (excerpt)

{"command":"search","query":"how are credentials checked","kind":"all","total":3,"ok":true,"schema_version":1,
 "hits":[{"grain":"symbol","name":"Check","symbol_kind":"method",
          "path":"internal/auth/auth.go","start_line":9,"end_line":9,
          "score":0.5081,"why":"semantic match","risk_level":"low","role":"impl","exported":true}, …]}

See JSON Contract & Errors.

Exit codes

0 success · 3 not initialized / index missing. See Exit Codes.

See also

Searching Effectively · Navigating Code · Command: graphs · Output Modes