Get started with vaultspec-ragLink to Get started with vaultspec-rag
Index your project, search its source code, and narrow the results to a file.
Step 1: Prepare a host installationLink to Step 1: Prepare a host installation
This tutorial starts the service from a host installation. Install it once per machine as a standalone tool, as the installation guide recommends:
Follow Install as a standalone tool.
Complete the default sparse-model access check.
Run the repository setup from your project root.
Follow Start and verify.
A project dependency or a prebuilt binary works too; see how to choose an installation.
A client installation carries no GPU packages and cannot start the service. If a host
installation on this machine already runs the service at the client’s release, a client
can follow Steps 2 to 4 with the uv run prefix: its server start reports the running
service instead of starting one.
Examples call vaultspec-rag directly, as a standalone tool does. Once verification
succeeds, return here for Step 2.
Step 2: Start the service and index your projectLink to Step 2: Start the service and index your project
From your project directory, start the service and submit indexing jobs:
Command
vaultspec-rag server start
vaultspec-rag index
server start first downloads any model files or the Qdrant index server that
the repository setup did not already fetch, showing the transfer, and then 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
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 searchLink to Step 3: Run your first search
When no search type is specified (no --type), search defaults to source code
and architecture decision records (ADRs), ranked together. Use --type code
to search source code only, as in the example below. Use --type vault for all
vault record types, or --type combined to include all three indexes.
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
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 projectLink to 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
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 finishedLink to When you are finished
Stop the service when you no longer need it:
Command
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 workLink to If a step didn’t work
If you still need help, report the problem.