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": 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 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.