query

What It Does

query searches indexed repository knowledge and returns matching hits for a question. It uses the shared retrieval planner/executor, but stays snapshot-scoped, so the answer is still tied to the chosen commit state.

When To Use / When Not To Use

When to use it

You want direct retrieval hits for a question.
You want to inspect what the snapshot knows at a specific commit.
You want a lightweight agent call before building a larger context packet.

When not to use it

You need a prompt-sized packet with token budgeting. Use context pack.
You want to resume active work from working memory. Use memory recall.

Syntax

pnpm ragit query [question] [--input <path|->] [--top-k <n>] \
  [--scope durable|session|harness|evidence|all] \
  [--at <sha>] [--view minimal|default|full] \
  [--format text|json|both]

Arguments And Options

question: A direct search question.
--input <path|->: Provide a JSON payload with question, topK, and optional at.
--top-k <n>: Control how many hits to return.
--scope durable|session|harness|evidence|all: Choose whether to search the durable snapshot only, explicit artifact scopes, or both.
--at <sha>: Query a specific snapshot SHA or prefix.
--view minimal|default|full: Choose how much hit detail to project.
--format text|json|both: Choose the output form.
--cwd <path>: Run against another repository.

Input And Output Contract

Positional input is fine for a quick human call.
Agents should prefer --input <path|-> when they need reproducible payloads.

{
  "question": "restore auth context",
  "topK": 5,
  "at": "HEAD"
}

JSON output returns query, snapshotSha, and hits.
JSON output also returns redactionSummary.
Each hit can carry artifact-aware metadata such as scope, originType, artifactId, artifactKind, authority, and confidence when the indexed chunk originated from reviewed artifact material inside the snapshot.
Output is always re-masked before printing or JSON projection.
--view minimal returns the smallest useful hit shape.
--view default returns the standard readable hit projection.
--view full keeps the richest text projection and is the most expensive for context windows.

Examples

Human terminal flow:

pnpm ragit query "restore auth context" --format both

Agent-oriented flow:

pnpm ragit query --input query.json --view minimal --format json

Failures And Cautions

Do not mix --input with positional question, --top-k, or --at.
If question is empty, the command fails.
query never reads working memory.
With --scope durable, it stays snapshot-only.
With --scope session|harness|evidence|all, it can merge explicit artifact/evidence overlays, but still returns sanitized output.

query

On this page