--- generator: "vaultspec-marketing discovery" title: "vaultspec-rag CLI reference - vaultspec-rag documentation" description: "Generated from the live command surface. Each entry lists the command’s arguments, options, types, defaults, and help text." url: "https://vaultspec.neve.md/docs/rag/cli.html" component: "vaultspec-rag" source_repository: "https://github.com/nevenincs/vaultspec-rag" source_path: "docs/cli.md" source_commit: "5e720868f2d535df6fb4e160cd787270051acda1" date_modified: "2026-10-06T17:52:27+02:00" --- [View as Markdown]() # vaultspec-rag CLI reference Generated from the live command surface. Each entry lists the command’s arguments, options, types, defaults, and help text. Global options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--target`, `-t` | directory | no | - | Directory containing .vault and .vaultspec | | `--verbose`, `-v` | boolean | no | off | Enable INFO logging | | `--debug`, `-d` | boolean | no | off | Enable DEBUG logging | | `--data-dir` | str | no | - | Index data directory (default: .vault/data/search-data) | | `--storage-dir` | str | no | - | Index data subdirectory relative to –data-dir | | `--status-dir` | str | no | - | Directory for service runtime files (default: ~/.vaultspec-rag) | | `--log-file` | str | no | - | Service log filename inside –status-dir | | `--version`, `-V` | boolean | no | off | Show version | | `--install-completion` | boolean | no | - | Install completion for the current shell. | | `--show-completion` | boolean | no | - | Show completion for the current shell, to copy it or customize the installation. | Commands - [search]() - [index]() - [clean]() - [install]() - [uninstall]() - [status]() - **server** - [doctor]() - [inventory]() - [warmup]() - [jobs]() - [logs]() - [preflight]() - [pause]() - [resume]() - [status]() - [reconcile]() - [start]() - [stop]() - **job** - [show]() - [pause]() - [resume]() - [stop]() - [retry]() - [delete]() - **projects** - [list]() - [unload]() - **updates** - [status]() - [start]() - [stop]() - [timing]() - **qdrant** - [install]() - [status]() - [clean]() - [quarantine]() - **storage** - [survey]() - [delete]() - [prune]() - [reconcile]() - [migrate]() - [restore]() - **preprocess** - [list]() - [check]() - [approve]() - [revoke]() - [run-one]() - [status]() search Search ADRs and source code by meaning by default. Uses the running service when available. Local search runs only with an explicit mandate (–allow-fallback or configured local-only mode). **Command** ```bash vaultspec-rag search ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `query` | str | yes | required | The search query text. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--type` | str | no | combined | Search area: vault documentation, source code, extracted documents, or all three with explicit combined. Without –type: ADRs and code. Aliases: docs, codebase, all. | | `--max-results`, `--limit` | int | no | 10 | Maximum number of results to show. Default 10 keeps the output focused. | | `--language` | str | no | - | Only show code results in this programming language. | | `--path` | str | no | - | Only show code results from this one exact project-relative path. Use –include-path to select a subtree or a glob. | | `--include-path` | str | no | - | Only show code results whose project-relative path matches this pattern. A plain pattern matches that path and everything under it; globs are accepted. Repeatable. | | `--exclude-path` | str | no | - | Hide code results whose project-relative path matches this pattern. A plain pattern matches that path and everything under it; globs are accepted. Repeatable. | | `--dedup-locales`, `--no-dedup-locales` | boolean | no | - | Collapse matching locale files into one representative result. Defaults to the configured value (on) when not specified. | | `--prefer` | str | no | - | Prefer one kind of code result: production, tests, or documentation. | | `--structure` | str | no | - | Only show code results for this source-code structure. | | `--function-name` | str | no | - | Only show code results from this function or method. | | `--class-name` | str | no | - | Only show code results from this class or struct. | | `--doc-type` | str | no | - | Only show document results with this type, such as ‘adr’ or ‘plan’. | | `--feature` | str | no | - | Only show document results for this feature tag. | | `--date` | str | no | - | Only show document results from this date (yyyy-mm-dd). | | `--tag` | str | no | - | Only show document results with this tag, without ‘#’. | | `--source-path` | str | no | - | Only show extracted-document results from this source path. | | `--extractor-id` | str | no | - | Only show document results emitted by this extractor. | | `--extractor-version` | str | no | - | Only show document results from this extractor version. | | `--locator-kind` | str | no | - | Only show document results with this locator kind. | | `--scores` | boolean | no | off | Show numeric relevance scores in human search output. | | `--port` | int | no | - | Service port (defaults to running service). | | `--allow-fallback` | boolean | no | off | If the selected service is not reachable, run the search locally instead of stopping with an error. | | `--verbose` | boolean | no | off | Show model loading and progress messages during local search. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | | `--timeout` | float | no | - | Connection and read timeout budget in seconds for searches handled by the service (default 300 seconds; override with VAULTSPEC\_RAG\_SEARCH\_TIMEOUT). | | `--freshness-policy` | str | no | immediate | Return immediately or wait within a bounded publication window. | | `--freshness-wait-seconds` | float | no | - | Publication wait bound in seconds; requires –freshness-policy bounded. | index Build or update the vault, code, and extracted-document search indexes. Uses the running service, or –borrow-gpu for explicit local GPU work. **Command** ```bash vaultspec-rag index ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--type` | str | no | all | What to index: vault, code, document, or combined. Aliases: docs, codebase, all. | | `--model` | str | no | - | Override the embedding model name. | | `--rebuild` | boolean | no | off | Delete the selected index data before rebuilding it. | | `--full` | boolean | no | off | Verify every stored payload against existing canonical proof through the running service; never creates or repairs proof. | | `--port` | int | no | - | Service port (defaults to running service). | | `--dry-run` | boolean | no | off | Show the resolved code/document admission summary without indexing. Use with –type code, document, combined, or the default all alias. | | `--dry-run-limit` | int | no | 50 | Maximum source-code file paths to show in human dry-run output. JSON output still includes every path. | | `--exclude` | str | no | - | Ad-hoc exclusion pattern (repeatable, gitignore syntax). | | `--borrow-gpu` | boolean | no | off | Acquire a borrower lease, pause a compatible running service, then run this index command locally before resuming it. | | `--no-preprocess` | boolean | no | off | Load no document-preprocessing rules for this in-process index run (VAULTSPEC\_RAG\_PREPROCESS=off). Applies to in-process indexing only; a running service uses the preprocess mode it was started with. | | `--verbose` | boolean | no | off | Show model loading and indexing progress messages. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | clean Delete selected index data without rebuilding it. Does not load models or use the GPU. **Command** ```bash vaultspec-rag clean ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `clean_type` | str | yes | required | What to delete: vault, code, document, or combined/all. Required so nothing is deleted by accident. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--yes`, `-y` | boolean | no | off | Confirm the destructive wipe without prompting. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. Requires –yes so no prompt interrupts the JSON output. | install Set up vaultspec-rag in a workspace. Creates the required workspace folders, installs bundled rules and integration files, and syncs the files used by supported tools. By default, install also provisions the external dependencies the server-first default needs - the embedding/reranker models and the pinned Qdrant server binary - and ensures the optional MCP extra so the agent-facing MCP search surface can run, and asks before changing PyTorch package configuration. Use –local-only for the minimal local backend (skips the binary), the finer –skip-models/–skip-qdrant flags for partial opt-out, –no-mcp for a CLI-only workspace without the mcp dependency, and –no-provision to set up the workspace only; use –yes or –no-torch-config for non-interactive runs. The model files and the Qdrant server are each checked against digests compiled into vaultspec-rag before they are used. A client installation is given neither, and a host that cannot run the service yet gets them from server start once it can. Exits non-zero when a step it was asked to run failed. **Command** ```bash vaultspec-rag install ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--target`, `-t` | directory | no | - | Workspace path (default: current working directory). | | `--upgrade` | boolean | no | off | Refresh bundled rules and integration files even if present. | | `--dry-run` | boolean | no | off | Preview changes without writing. | | `--force` | boolean | no | off | Override existing files. Never answers the torch-config confirmation prompt; use –yes for that. | | `--skip` | str | no | () | Skip a component (repeatable). | | `--mode` | choice | no | - | Provisioning mode: ‘tool’ (default, launched via uvx), ‘dependency’ (a runtime project dependency resolved through the project’s own venv, ships in built distributions), or ‘dev’ (the default dev dependency group; renders like dependency but does not ship in built distributions). Auto-detected from pyproject.toml when omitted. | | `--torch-config`, `--no-torch-config` | boolean | no | on | Configure the CUDA PyTorch package source in pyproject.toml. –no-torch-config takes precedence over –yes. | | `--tool-repair`, `--no-tool-repair` | boolean | no | on | Check whether a persistent uv tool environment holds a processor-only torch build, and report the command that repairs it. Nothing is installed or replaced by this check. –no-tool-repair skips it entirely. | | `--torch-group` | str | no | - | Place the managed CUDA torch direct-dependency under the PEP 735 \[dependency-groups\].NAME surface instead of \[project\].dependencies, so a dev-only consumer does not leak torch into its published requirements. Defaults the group name to ‘dev’ when passed without a value. Omit the flag entirely to keep the historic \[project\].dependencies placement. The group must be enabled for the resolve (`uv sync --group NAME`) for the cu130 pin to apply. | | `--yes`, `-y` | boolean | no | off | Skip the PyTorch configuration prompt. Required for non-interactive installs unless –no-torch-config is used. | | `--sync` | boolean | no | off | Run `uv sync --reinstall-package torch` after PyTorch configuration changes are applied. | | `--provision`, `--no-provision` | boolean | no | on | Provision external dependencies (models and the Qdrant server binary) after enrollment. On by default; –no-provision sets up the workspace only. | | `--mcp`, `--no-mcp` | boolean | no | on | Enroll the agent-facing MCP search surface and reconcile its optional dependency at RAG’s existing project placement. On by default; –no-mcp sets up a CLI-only workspace without the mcp dependency (and, on Windows, without pywin32). | | `--local-only` | boolean | no | off | Use the on-disk store instead of the supervised Qdrant server: skips the Qdrant binary download and persists the local backend so `server start` honours it. The minimal / CI / air-gapped alternative to the server-first default. | | `--skip-models` | boolean | no | off | Skip the embedding/reranker model provisioning step. | | `--skip-qdrant` | boolean | no | off | Skip the Qdrant server binary provisioning step. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | | `--no-hints` | boolean | no | off | Suppress next-step advisory hints. | uninstall Remove vaultspec-rag setup from a workspace. Requires –force to execute; use –dry-run to preview what would be removed instead. **Command** ```bash vaultspec-rag uninstall ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--target`, `-t` | directory | no | - | Workspace path (default: current working directory). | | `--remove-data` | boolean | no | off | Also remove index data under .vault/data/. | | `--dry-run` | boolean | no | off | Preview changes without removing. | | `--force` | boolean | no | off | Required to execute. Uninstall is destructive. | | `--skip` | str | no | () | Skip a component (repeatable). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | status Show the service, this installation’s compute, the project’s active features, and its index. The overview names the service and where it is, whether this installation is a client or an inference host, and whether it can run inference. The `Compute:` line names the machine’s GPU and the environment’s torch build separately, and a `Fix:` line appears only when the environment is broken, never for a client that has no GPU work to do. The project’s preprocessing hooks are always shown; Typesafe, reranking and the file watcher are shown when a service answers. A service from another release is reported as a release mismatch rather than read around. **Command** ```bash vaultspec-rag status ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | | `--verbose` | boolean | no | off | Also verify this installation’s GPU by loading torch, and show the interpreter, the support profile limits, and the per-domain index generations. | server doctor Report readiness across two axes: installed dependencies (torch, models, qdrant binary) and the live service (a running daemon’s health). A dead daemon is reported as not ready. Each pinned model’s cached files are hashed against the digests compiled into this tool, which reads several gigabytes and takes a few seconds; a model with no such digests is reported as unpinned. **Command** ```bash vaultspec-rag server doctor ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit one structured JSON outcome. It is the readiness snapshot. | server inventory Emit persisted monitor inventory without creating or operating a service. **Command** ```bash vaultspec-rag server inventory ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `operation` | str | yes | required | repositories or storage/survey | | `parameters` | str | yes | required | Bounded JSON string parameters | Options None. server warmup Fetch and check the model files the service loads. Each default model is downloaded from the Hugging Face Hub, or the mirror the hub endpoint setting names, at a pinned commit, and every file is compared with a SHA256 digest compiled into vaultspec-rag. A model that is already cached and passes costs no download; one you named yourself is reported as unpinned. A client installation needs no models and is told so. Exits non-zero when a model could not be fetched, fails its check, or is missing while the hub is in offline mode. **Command** ```bash vaultspec-rag server warmup ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server jobs Show recent index update activity from the running service. **Command** ```bash vaultspec-rag server jobs ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--limit` | int | no | 20 | Maximum number of matching jobs to show. | | `--state` | str | no | - | Filter by job state: active, waiting, finished, failed, or cancelled. | | `--index` | str | no | - | Filter by index type: vault or code. | | `--started-by` | str | no | - | Filter by who started the job: manual requests or automatic updates. | | `--query`, `-q` | str | no | - | Filter by text in job id, outcome, or progress. | | `--failed` | boolean | no | off | Show only failed jobs. | | `--job-id` | str | no | - | Show details for a job id or prefix. | | `--since` | float | no | - | Show jobs updated within the last N seconds. | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. Always use this for scripted waits: the human summary line unconditionally contains the words ‘active’ and ‘waiting’. | | `--watch` | boolean | no | off | Open the interactive jobs interface with per-job controls. | | `--interval` | float | no | 2.0 | Seconds between refreshes in the interactive interface. | server logs Show grouped raw service and Qdrant logs live or offline. **Command** ```bash vaultspec-rag server logs ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--limit` | int | no | 200 | Maximum recent lines returned per selected source. | | `--source` | choice | no | all | Managed log source: service, qdrant, or all. | | `--job-id` | str | no | - | Keep lines containing this job ID. | | `--contains` | str | no | - | Keep lines containing this text. | | `--port` | int | no | - | Use this live service port before reading retained local logs. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server preflight Observe service quiescence and device capacity without authorizing GPU work. **Command** ```bash vaultspec-rag server preflight ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server pause Hold the running service at safe checkpoints. **Command** ```bash vaultspec-rag server pause ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server resume Release a paused service. **Command** ```bash vaultspec-rag server resume ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server status Show the human operator summary for server readiness, work, and next checks. A running service’s summary lists its optional features: the `Typesafe:` line reports the daemon’s classifier enrollment and observed usability, not the calling shell’s key, and `Reranking:`, `Preprocessing:` and `File watcher:` say whether each is on. JSON includes `data.health.features` when health is available. A stopped or crashed service prints one line naming its state and how to start it. See [Typesafe enrollment]() for state meanings; status never makes a paid classification call. The address in status output is the backend address. Human, verbose and JSON status output do not currently report the browser monitor URL. Run `server start` to display its recorded `Monitor:` URL; an already-running owned service is reused. See [browser monitor setup](). **Command** ```bash vaultspec-rag server status ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. Preserves exit codes 0 (running), 3 (stopped), 4 (crashed or divergent), and 5 (starting: models loading, not yet serving). | | `--verbose` | boolean | no | off | Show process, heartbeat, service identity, model, and extra diagnostic details in the human output. | server reconcile Wait for the running service to republish its discovery records. Non-destructive: nothing is written, deleted, stopped, or restarted. Exits 0 once discovery agrees, 1 if it does not converge in time. **Command** ```bash vaultspec-rag server reconcile ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--timeout` | float | no | 35.0 | Seconds to wait for convergence before reporting unresolved. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. Preserves exit codes 0 (converged) and 1 (not converged). | server start Start the background search service. Defaults to the managed Qdrant server backend (server mode); pass –local-only for the on-disk store. Before the service is started, a host installation fetches what it needs and does not have: the model files, each checked against digests compiled into vaultspec-rag, and the managed Qdrant server, unless that download is switched off. A client installation is refused and fetches nothing. A fetch that fails stops the start with its cause and its remedy. Waits until the service is ready and records how the CLI can reach it. Also starts the managed browser monitor. Its port begins at the actual backend port plus one and increments until free: `--port 9000` first tries monitor port 9001. Human output prints the monitor’s access link as `Monitor: http://127.0.0.1:/#capability=`; JSON includes `data.monitor_port` and `data.monitor_url` when recorded. The link is a credential: the monitor operates the service only for a caller presenting its capability. An already-running response redisplays the recorded link. Requires the compiled `vaultspec-rag-monitor` command on PATH or its absolute path in `VAULTSPEC_RAG_MONITOR_BINARY`. Startup does not compile the frontend. See [browser monitor setup](). Successful starts and already-running responses include Typesafe enrollment from the daemon (`Typesafe:` in human output, `data.typesafe` in JSON). Set the dedicated key before launching the server; attaching to an existing server does not change its environment. Enrollment alone does not confirm a valid, funded key: the first search evaluation establishes usability. See [Typesafe enrollment](). **Command** ```bash vaultspec-rag server start ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | 8766 | Port for the background search service. | | `--updates`, `--no-updates` | boolean | no | - | Enable or disable automatic index updates when files change (default: enabled). | | `--update-delay-ms` | int | no | - | Delay before indexing a burst of file changes, in milliseconds. | | `--repeat-update-delay-s` | float | no | - | Minimum wait before automatically updating a project again, in seconds. | | `--local-only` | boolean | no | off | Use the on-disk local store instead of the default managed Qdrant server. This is the first-class opt-out for CI, offline, and small-project hosts. | | `--qdrant`, `--no-qdrant` | boolean | no | - | Select the managed Qdrant server for this start, or decline it. –qdrant overrides a saved or exported local-only choice for this run without rewriting it; –local-only still wins when both are given. Unset leaves the current setting in force. | | `--qdrant-auto-provision`, `--no-qdrant-auto-provision` | boolean | no | - | Download and verify the managed Qdrant server when it is missing (default: enabled). With –no-qdrant-auto-provision, start prints the install command instead. Unset leaves the VAULTSPEC\_RAG\_QDRANT\_AUTO\_PROVISION setting in force. | | `--no-preprocess` | boolean | no | off | Kill switch: the service loads no document-preprocessing rules for any root (forwards VAULTSPEC\_RAG\_PREPROCESS=off). | | `--json` | boolean | no | off | Emit one structured JSON outcome. An already-running owned service is the success `already_running` (exit 0), so a supervising broker can attach rather than treating it as a fault. | server stop Stop the background search service. Also stops the daemon-owned browser monitor and clears its recorded port assignment. A missing or already-stopped service is an idempotent success; failure to stop the monitor is a failed stop. Separately launched development monitors retain their own lifecycle. **Command** ```bash vaultspec-rag server stop ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Stop the service answering on this port, resolving its identity from /health, or from a matching launch identity in the status file before its listener opens. Use when the service runs on a non-default port or the status file diverges from the running instance. | | `--json` | boolean | no | off | Emit one structured JSON outcome. An already-stopped service is the success `already_stopped` (exit 0); a stop that leaves the service running (unconfirmed identity) is `identity_unconfirmed` (exit 1) in both output modes. | | `--orphans` | boolean | no | off | Reap surplus vaultspec-rag daemons that lost the machine-singleton race and linger holding no port, lock, or discovery pointer, invisible to a normal stop. Confirm-then-reap, scoped to this singleton’s port; the live singleton, isolated-config, and foreign-worktree daemons are always spared. | server job show Show one exact job resource; human output accepts a unique prefix. **Command** ```bash vaultspec-rag server job show ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `job_id` | str | yes | required | Exact job id or human-mode prefix. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit one structured JSON outcome. | server job pause Request a cooperative pause for one job. **Command** ```bash vaultspec-rag server job pause ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `job_id` | str | yes | required | Exact job id or human-mode prefix. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit one structured JSON outcome. | server job resume Resume one paused job through reconciliation. **Command** ```bash vaultspec-rag server job resume ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `job_id` | str | yes | required | Exact job id or human-mode prefix. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit one structured JSON outcome. | server job stop Request cancellation without disabling automatic updates. **Command** ```bash vaultspec-rag server job stop ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `job_id` | str | yes | required | Exact job id or human-mode prefix. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit one structured JSON outcome. | | `--force` | boolean | no | off | Request force termination; currently rejected when unsupported. | server job retry Create a linked retry for one retryable terminal job. **Command** ```bash vaultspec-rag server job retry ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `job_id` | str | yes | required | Exact job id or human-mode prefix. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit one structured JSON outcome. | server job delete Delete one terminal job from retained history. **Command** ```bash vaultspec-rag server job delete ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `job_id` | str | yes | required | Exact job id or human-mode prefix. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit one structured JSON outcome. | server projects list List projects currently loaded by the running search service. **Command** ```bash vaultspec-rag server projects list ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server projects unload Unload a project from the running search service. **Command** ```bash vaultspec-rag server projects unload ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `project` | str | yes | required | Project to unload. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server updates status Show automatic index update settings and projects. **Command** ```bash vaultspec-rag server updates status ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | | `--root` | str | no | - | Only report controllers for this project root. | | `--source` | str | no | - | Only report this index source. | | `--state` | str | no | - | Only report controllers in this state. | | `--limit` | int range | no | 256 | Most controllers to report. | server updates start Start automatic index updates for a project. **Command** ```bash vaultspec-rag server updates start ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `project` | str | yes | required | Project to keep indexed. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server updates stop Stop automatic index updates for a project. **Command** ```bash vaultspec-rag server updates stop ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `project` | str | yes | required | Project to stop updating automatically. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server updates timing Change automatic index update timing. **Command** ```bash vaultspec-rag server updates timing ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `project` | str | yes | required | Project to update timing for. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--update-delay-ms` | int | no | - | Delay before indexing a burst of file changes, in milliseconds. | | `--repeat-update-delay-s` | float | no | - | Minimum wait before automatically updating a project again, in seconds. | | `--port` | int | no | - | Service port (defaults to running service). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server qdrant install Install the managed Qdrant server under the service directory. The release archive is downloaded from the configured release source, and the archive and the executable inside it are each compared with a SHA256 digest compiled into vaultspec-rag before anything is installed. An install that already passes its check costs no download. A client installation, and a host that cannot run the service yet, need no server and are told so. Exits non-zero when the install failed; a previous install is left as it was. **Command** ```bash vaultspec-rag server qdrant install ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--upgrade` | boolean | no | off | Replace an installed Qdrant server that fails its check. An install that passes is left alone. | | `--dry-run` | boolean | no | off | Preview the version, release package, download, install path, and digest without downloading or writing anything. | | `--archive` | path | no | - | Install from a local copy of the release package instead of downloading it, for a host with no route to the release source. The file passes the same checksum checks as a download, is read where it lies, and no request is made. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server qdrant status Show the managed Qdrant executable, address, connection, and process. **Command** ```bash vaultspec-rag server qdrant status ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--port` | int range | no | - | Qdrant HTTP port to check. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server qdrant clean Delete managed Qdrant server installs. Destructive: requires –yes. –keep-current preserves the current managed version. Index data is never touched. **Command** ```bash vaultspec-rag server qdrant clean ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--keep-current` | boolean | no | off | Preserve the current managed Qdrant version. | | `--yes` | boolean | no | off | Confirm deletion of managed Qdrant installs. | | `--dry-run` | boolean | no | off | Preview what would be removed. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server qdrant quarantine Move a corrupt collection out of the shared store so the server can start again. Run with no name to list collections; name one to quarantine it (requires –yes). The quarantined collection re-indexes on its next use; nothing is deleted. **Command** ```bash vaultspec-rag server qdrant quarantine ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `collection` | str | no | - | Collection to quarantine; omit to list the store. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--yes` | boolean | no | off | Confirm moving the named collection aside. | | `--dry-run` | boolean | no | off | Preview the move without touching the store. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server storage survey List stored RAG namespaces classified as live, orphaned, or unknown; –root looks up one root’s collection prefix and namespace. **Command** ```bash vaultspec-rag server storage survey ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | | `--orphaned` | boolean | no | off | Show only orphaned namespaces (prune candidates). | | `--unknown` | boolean | no | off | Show only unattributable (unknown) namespaces. | | `--root` | str | no | - | Narrow to one root’s namespace and report its authoritative collection prefix (works even for a root not yet indexed). | | `--fresh` | boolean | no | off | Force the service to recompute the survey instead of answering from its cached snapshot (slower; walks every namespace). | server storage delete Delete one named RAG namespace, addressed by its r{hash}\_ prefix or by –root (the sanctioned per-root teardown for harnesses). **Command** ```bash vaultspec-rag server storage delete ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `prefix` | str | no | - | The namespace prefix to delete (r{hash}\_). | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--root` | str | no | - | Address the namespace by its source root path instead of the prefix; an already-absent namespace is a success (exit 0). | | `--yes`, `-y` | boolean | no | off | Apply the deletion. | | `--dry-run` | boolean | no | off | Preview without deleting. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | | `--allow-unknown` | boolean | no | off | Permit deleting a prefix the manifest cannot attribute (dangerous). | server storage prune Reclaim every orphaned RAG namespace (source root gone). **Command** ```bash vaultspec-rag server storage prune ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--yes`, `-y` | boolean | no | off | Apply the prune. | | `--dry-run` | boolean | no | off | Preview without deleting. | | `--debris` | boolean | no | off | Also remove config-less collection dirs left behind by crashes (unloadable by the server; filesystem delete). | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server storage reconcile Shrink existing collections to the bounded segment geometry. **Command** ```bash vaultspec-rag server storage reconcile ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--yes`, `-y` | boolean | no | off | Apply the reconcile. | | `--dry-run` | boolean | no | off | Preview without changing. | | `--limit` | int | no | 0 | Max collections to reconcile (0 = every drifted collection). | | `--wait`, `--no-wait` | boolean | no | on | Wait for the optimizer to converge before reporting. With –no-wait the updates are issued and reclamation is reported by a later run, since mid-flight sizes are meaningless. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server storage migrate Migrate a root’s index between local and server backends. **Command** ```bash vaultspec-rag server storage migrate ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `root` | str | yes | required | The workspace root whose index to migrate. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--to` | str | yes | required | Target backend: ‘server’ or ‘local’. | | `--yes`, `-y` | boolean | no | off | Apply the migration. | | `--dry-run` | boolean | no | off | Preview without copying. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | server storage restore Restore an archived namespace into a named destination root. The destination must hold no collections; there is no override. Applying a restore needs a non-Windows Qdrant server. Previewing the destination with –dry-run works on any platform. **Command** ```bash vaultspec-rag server storage restore ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `archive` | str | yes | required | Path to the archive directory holding the snapshot manifest. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--root` | str | yes | required | Destination root path the restored namespace is keyed to. | | `--yes`, `-y` | boolean | no | off | Apply the restore. | | `--dry-run` | boolean | no | off | Preview the destination collections without writing. | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | preprocess list List resolved preprocess rules for the project. **Command** ```bash vaultspec-rag preprocess list ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | preprocess check Validate .vaultragpreprocess.toml and report configuration problems. **Command** ```bash vaultspec-rag preprocess check ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | preprocess approve Approve this project’s current preprocess rules so indexing may run their commands. Any later change to the rules needs approval again. **Command** ```bash vaultspec-rag preprocess approve ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | preprocess revoke Withdraw approval of this project’s preprocess rules so they stop running. **Command** ```bash vaultspec-rag preprocess revoke ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | preprocess run-one Run the matching rule against one file (no indexing). **Command** ```bash vaultspec-rag preprocess run-one ``` Arguments | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `path` | str | yes | required | Source file to preprocess. | Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. | preprocess status Report the preprocess mode, approval, config presence, and rule count. **Command** ```bash vaultspec-rag preprocess status ``` Arguments None. Options | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--json` | boolean | no | off | Emit JSON for scripts instead of human text. |