> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# nora retrieval

> Run searches from the CLI, manage retrieval presets, diagnose failures.

The `retrieval` command group is the CLI surface for the retrieval subsystem — the layer between agent queries and your knowledge.

## Commands

| Command                           | Description                                            |
| --------------------------------- | ------------------------------------------------------ |
| `retrieval search <query>`        | Run a search query.                                    |
| `retrieval diagnose <cluster-id>` | Pin first broken retrieval stage in a failure cluster. |
| `retrieval presets list`          | List all retrieval presets.                            |
| `retrieval presets get <id>`      | Fetch one preset's config.                             |
| `retrieval presets upsert <id>`   | Create/replace a preset.                               |
| `retrieval presets delete <id>`   | Delete a preset.                                       |

## `retrieval search`

```bash theme={null}
nora retrieval search "how do refunds work" \
  --preset high-precision \
  --k 10 \
  --method hybrid \
  --filters '{"tag": "billing"}'
```

Runs the query and prints results.

Flags:

* `<query>` (positional) — the text to search.
* `--preset <preset-id>` — use a saved preset (see below).
* `--k <n>` — top-K to return.
* `--method vector|keyword|hybrid|kg_rooted` — retrieval mode.
* `--filters <json>` — metadata filter expression.
* `--include-subgraph` — expand results to include related graph nodes.
* `--graph-expansion` — enable knowledge-graph traversal.

Without `--preset`, uses the workspace default preset.

## `retrieval diagnose`

```bash theme={null}
nora retrieval diagnose cl_billing_misses
```

For a failure cluster (Signals → cluster), pins the first broken retrieval stage. Answers "where in the retrieval pipeline did this cluster's failures actually happen?" — filter dropped it? Vector score too low? Reranker demoted it? Grounding rejected it?

Output identifies the specific stage and shows evidence per failing trace.

Best used as a targeted diagnostic before deciding which retrieval lever to tune.

## Presets

Presets bundle retrieval settings (top-K, weights, filters, reranker) so multiple Agents can share one config.

### List

```bash theme={null}
nora retrieval presets list
```

### Get

```bash theme={null}
nora retrieval presets get high-precision
```

Prints the preset's config as JSON.

### Upsert

```bash theme={null}
nora retrieval presets upsert high-precision \
  --name "High Precision" \
  --config '{
    "k": 6,
    "method": "hybrid",
    "vector_weight": 0.6,
    "keyword_weight": 0.4,
    "reranker": true,
    "cutoff": 0.2
  }'
```

Creates the preset if it doesn't exist; replaces it if it does.

Flags:

* `<id>` (positional, required) — the preset's ID.
* `--name <n>` (required) — display name.
* `--config <json>` (required) — the full preset config. See [Retrieval presets](/build/retrieval/presets) for the field reference.

### Delete

```bash theme={null}
nora retrieval presets delete high-precision
```

Fails if any Agent references the preset. Update those Agents first.

## Recipes

### Iteratively tune a preset

```bash theme={null}
# Snapshot current
nora retrieval presets get high-precision --json > preset.json

# Edit locally (e.g., bump vector_weight)
jq '.config.vector_weight = 0.7' preset.json > preset-tuned.json

# Re-upsert
nora retrieval presets upsert high-precision \
  --name "$(jq -r '.name' preset-tuned.json)" \
  --config "$(jq -c '.config' preset-tuned.json)"

# Test with a real query
nora retrieval search "sample question" --preset high-precision
```

### Compare two presets side-by-side

```bash theme={null}
diff <(nora retrieval search "refund" --preset old) \
     <(nora retrieval search "refund" --preset new)
```

### Test retrieval isolation between tenants

```bash theme={null}
nora retrieval search "sensitive-question" \
  --filters '{"tenant":"acme"}'
# Should NOT return chunks with tenant="other"
```

Combine with the app's isolation-test view for a definitive check.

### Attach a preset via `agents sources update`

Once a preset is dialed in, attach it to an Agent's data source:

```bash theme={null}
nora agents sources update ag_support \
  --kind documents_folder \
  --source-id billing \
  --set-preset high-precision
```

See [`nora agents`](/cli/agents) for full source attachment options.

## What the CLI does NOT do

* **Save retrieval results to a dataset** — use the app's Trace view for that (search a trace, add the retrieval step to a dataset).
* **Configure grounding graphs directly** — grounding is enabled via preset config (`{"grounding": {"graph_id": "..."}}`), but graph editing is via [`nora causal`](/cli/causal).

## Debugging queries

* Add `--json` for the raw score breakdown per result.
* Try `--method vector`, then `--method keyword` separately to see which pass is stronger.
* If the right chunk exists but doesn't rank, `retrieval diagnose` on a cluster containing similar queries usually explains why.