stella search

Find the files that answer a question you can only describe in words — the same search tool the agent reaches for on every turn, run from your shell. Ranks semantically when an embedder is configured, and degrades honestly through graph symbol-name matching and then a file scan when it is not.

Synopsis

stella search "<query>" [--format text|json]

What it does

stella search runs the exact dispatch ladder the agent's search tool runs inside a turn:

The answer always states which strategies ran (via: …), so a result you get from the CLI is never ambiguous about how sharp it is.

query takes whatever form you have it in — a sentence, a behaviour description, or a bare symbol/file name — exactly as the agent's tool accepts it.

Examples

Ask a question in plain English:

stella search "where are request headers sanitized before logging"

A symbol name works just as well as a sentence:

stella search "what calls resolve_provider"

--format json

For scripted testing — feeding real queries through the exact ranking the agent uses and reading the answer back as data:

stella search "the retry/backoff policy for failed HTTP requests" --format json

{
  "schema_version": 1,
  "query": "the retry/backoff policy for failed HTTP requests",
  "ok": true,
  "strategies": ["semantic (embedding rank over the code-graph index)"],
  "note": null,
  "hits": [
    {
      "path": "crates/stella-core/src/retry.rs",
      "why": "ranked by MEANING against your query — best match is `RetryPolicy` (struct) at line 12 (cosine 0.612)"
    }
  ],
  "content": "search `...` — N result(s) at depth 10\nvia: semantic\n..."
}

The parts a test script asserts on ride as data, not prose: hits is the ranking in rank order (each with the why phrase the agent reads), strategies lists which rungs of the ladder actually ran — more than one entry means an earlier rung came back empty — and note carries the degradation reason verbatim when the semantic rung was skipped or failed. content is still the exact rendered text the agent would receive, and error is null on success.

The command exits non-zero on failure even under --format json, so a script can check the exit code without parsing the body — the JSON envelope on stdout stays valid either way, with ok: false and error set.

Two environment dials tune the rendering, the same ones the agent's registration reads: STELLA_SEARCH_DEPTH (how much is said about the top hit) and STELLA_SEARCH_BUDGET (the answer's character allowance). They shape content only — the hits ranking is unaffected.