---
title: 'rag'
description: 'Operate the managed retrieval index bound to a running agent installation: collections, documents, similarity queries and ingest jobs.'
position: 20
---

# stackbone rag

> `stackbone rag` targets a **running agent installation**. With no `--agent`
> it uses the local-dev installation linked to the current project, so
> [`stackbone dev`](/docs/cli/reference/dev) must be running. See
> [target resolution](/docs/cli/reference/conventions#target-resolution).
> Every verb accepts `--json` and emits the
> [standard envelope](/docs/cli/reference/conventions#json-output).

Operate the managed retrieval index bound to the targeted installation.
The document and query verbs require `--collection <name>`; `jobs` takes it
as an optional filter, and `retry`/`cancel` address a job by id and take none.

| Command                                   | Purpose                                                                                  |
| ----------------------------------------- | ---------------------------------------------------------------------------------------- |
| `stackbone rag collections list`          | List collections with per-collection document and chunk counts.                          |
| `stackbone rag collections create <name>` | Create an empty collection.                                                              |
| `stackbone rag collections remove <name>` | Delete a collection and every document under it. Requires `--yes`.                       |
| `stackbone rag list`                      | List documents in `--collection`. `--limit` is 1-200 (default 50), with `--cursor`.      |
| `stackbone rag get <docId>`               | Download a document original to stdout (or `--out <path>`).                              |
| `stackbone rag ingest <path>`             | Upload a local `.txt`/`.md`/`.pdf` (≤ 25 MiB) into `--collection`, staging an async job. |
| `stackbone rag query <text>`              | Run a similarity query over `--collection`. `--topk` is 1-50 (default 10), `--model`.    |
| `stackbone rag remove <docId>`            | Delete a document (cascades to its chunks). Requires `--yes`.                            |
| `stackbone rag jobs`                      | List async ingest jobs, optionally filtered by `--collection`. Same paging as `list`.    |
| `stackbone rag retry <jobId>`             | Re-enqueue a failed ingest job. Requires `--yes`.                                        |
| `stackbone rag cancel <jobId>`            | Cancel a non-terminal ingest job. Requires `--yes`.                                      |

`list` and `jobs` page with `--limit`/`--cursor`, described under
[pagination](/docs/cli/reference/conventions#pagination). The four verbs
marked above refuse to run without `--yes`, described under
[destructive verbs](/docs/cli/reference/conventions#destructive-verbs).

**JSON payload**

```jsonc
// rag ingest
{ "schema_version": 1, "job_id": "job_1", "status": "queued" }

// rag query
{ "schema_version": 1,
  "items": [{ "id": "doc_1", "chunk_idx": 0, "score": 0.83, "content": "…", "metadata": {} }],
  "dimensions": 1536, "embedded_with": "text-embedding-3-small" }

// rag jobs
{ "schema_version": 1,
  "items": [{ "id": "job_1", "collection": "docs", "status": "failed", "attempts": 2,
              "error": "…", "created_at": "2026-06-01T10:00:00Z", "finished_at": null }],
  "nextCursor": null, "prevCursor": null }
```

**A job holds one of five statuses**: `queued`, `running`, `succeeded`,
`failed`, `cancelled`. `retry` re-enqueues a `failed` job from the original it
stored at upload. `cancel` only takes a job that has not reached a terminal
status.

`rag query <text>` embeds the query text **server-side** with the deployment's
configured model provider, then runs the similarity search against
`--collection`. The response carries the ranked chunks, the vector `dimensions`
and the model it embedded with (`embedded_with`).

Documents ingested here live under the reserved `rag/` key prefix of the
installation's object store, which
[`stackbone storage`](/docs/cli/reference/storage) refuses to write to or
delete from.

**Exit codes**: `0` ok · `4` not found (unknown collection/doc/job) ·
`5` permission (destructive verb without `--yes`) · `1` generic (missing
`--collection`, unsupported file type).
See [exit codes](/docs/cli/reference/conventions#exit-codes).