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 must be running. See target resolution. Every verb accepts --json and emits the standard envelope.

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. The four verbs marked above refuse to run without --yes, described under destructive verbs.

JSON payload

// 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": 0,
              "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. One job is one ingest run, so attempts is always 0: a retry starts a new run rather than counting against the old one.

retry takes a failed job and re-ingests the original the upload stored. The answer carries a new job id, and the failed job keeps its own history. retry refuses a job in any other state ("Only a failed ingest run can be retried.") and exits 1.

cancel takes a job that has not reached a terminal state and flips it to cancelled. It is best effort and state-only: a run that is already mid-flight keeps executing. cancel refuses a terminal job ("Job is already in a terminal state.") and exits 1. Both verbs answer with the job and the status it now holds: { "schema_version": 1, "id": "job_1", "status": "queued" }.

jobs filters on --collection after it reads the page, so a filtered page can come back with fewer rows than --limit and a nextCursor still set. Keep following the cursor until it is null rather than stopping on a short page.

ingest stores the file, records the document, then hands the parsing, chunking and embedding to the installation's workflow runtime. ingest refuses in two cases, and both exit 1.

Upload the same bytes twice into one collection and the second one comes back as a duplicate. The check is per collection, so the same file in a second collection still goes through.

An installation with no workflow runtime has nothing to ingest with, so the upload fails with rag_ingest_unavailable. That is a workspace that ships no workflows, or a stackbone dev that has not armed them yet. ingest already recorded the document, so this refusal leaves it staged and a second attempt at the same file comes back as a duplicate. Remove the staged document first, then ingest again:

stackbone rag remove <docId> --collection docs --yes
stackbone rag ingest ./handbook.md --collection docs

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). A deployment with no model provider has nothing to embed the text with, so the query fails and exits 1. See local development → model provider.

Documents ingested here live under the reserved rag/ key prefix of the installation's object store, which stackbone storage refuses to write to or delete from.

Exit codes: 0 ok · 4 not found (unknown collection, document or job) · 5 permission (destructive verb without --yes) · 1 generic (missing --collection, an unsupported file type, a file over 25 MiB, a duplicate document, no workflow runtime to ingest with, no model provider to embed a query with, a retry or cancel the job's state does not allow). See exit codes.