vaultspec-rag

Get started with vaultspec-rag

Copied from vaultspec-rag's own documentation, and read against the pages written here at commit 04610a5c. Nothing in it needed answering differently.

Before you copy these

Every command below is written with the uv run prefix, which resolves only if you installed into a project. If you installed as a tool or as a binary, drop it and run vaultspec-rag bare; if you run it without installing, it becomes uvx --from "vaultspec-rag[gpu]" vaultspec-rag. Choose an install route sets out the four routes and which prefix each one needs.

Index your project, search its source code, and narrow the results to a file.

Step 1: Prepare an inference host

This tutorial starts and uses the resident inference service in the same project environment. Open the installation guide, read the installation lanes, and choose “Adding it to a project” with the [gpu] extra. Work from your project root. Complete the normal project setup to download the models, including the default sparse-model access check, then follow “Verify the install.”

A base or [mcp] client installation is intentionally model-free and cannot perform this tutorial’s server start step by itself. There is no [rag] extra.

Examples use the uv run prefix, which runs the command inside a project environment. If you installed vaultspec-rag as a standalone tool, drop the prefix and call vaultspec-rag directly; see the installation guide for lane selection.

Once verification succeeds, return here for Step 2.

Step 2: Start the service and index your project

From your project directory, start the service and submit indexing jobs:

Command

uv run vaultspec-rag server start
uv run vaultspec-rag index

server start waits until the service is ready. index prints IDs for the jobs it submits. Indexing continues after the command returns.

Open the live job view:

Command

uv run vaultspec-rag server jobs --watch

Match the first eight characters of the returned job IDs and check the project path. Wait until each submitted job shows finished before continuing. For jobs no longer in view, inspect a job by ID.

If a submission fails or a job shows failed or cancelled, follow the verification guide.

Step 3: Run your first search

Choose a function you know exists in your indexed project. Replace the example query with its name and a brief description of its behavior:

Command

uv run vaultspec-rag search "parse_query convert query text into filters" --type code

The --type code option searches source files. Inspect the returned file paths and matching passages to find your function. A file may have several matching passages.

If no results appear, use the verification guide and query guidance before continuing.

Step 4: Narrow the search to part of your project

Reuse your query from Step 3, adding a filter for one file. Replace src/search.py with a project-relative path from the results, keeping forward slashes and omitting any :LINE suffix:

Command

uv run vaultspec-rag search "parse_query convert query text into filters" --type code --path "src/search.py"

Check that every result belongs to the selected file. The --path option matches an exact project-relative path.

See the filter reference for other ways to narrow a search.

When you are finished

Stop the service when you no longer need it:

Command

uv run vaultspec-rag server stop

Stopping the service leaves stored indexes in place. Next session, start the service again. For stale indexes or configuration changes, see reindexing.

If a step didn’t work

• Resolve installation failures.

• Investigate missing or incomplete results.

• Improve poor matches.

If you still need help, report the problem.

Where to go next

• Search and index your project

• Understand the architecture

• Command-line reference