---
generator: "vaultspec-marketing discovery"
title: "Get started with vaultspec-rag - vaultspec-rag documentation"
description: "Index your project, search its source code, and narrow the results to a file."
url: "https://vaultspec.neve.md/docs/rag/getting-started.html"
component: "vaultspec-rag"
source_repository: "https://github.com/nevenincs/vaultspec-rag"
source_path: "docs/getting-started.md"
source_commit: "ff281ac4c327a761a9bcd9edff78f55246952ba0"
date_modified: "2026-10-06T13:30:20+02:00"

---

[View as Markdown](<https://vaultspec.neve.md/docs/rag/getting-started.md>)

# Get started with vaultspec-rag

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

## 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](<https://vaultspec.neve.md/docs/rag/installation.html>) recommends:

1. Follow [Install as a standalone tool](<https://vaultspec.neve.md/docs/rag/installation.html#install-as-a-standalone-tool>).
2. Complete the [default sparse-model access check](<https://vaultspec.neve.md/docs/rag/installation.html#the-model-cache-and-its-first-download>).
3. Run the [repository setup](<https://vaultspec.neve.md/docs/rag/installation.html#set-up-each-repository>) from your project root.
4. Follow [Start and verify](<https://vaultspec.neve.md/docs/rag/installation.html#start-and-verify>).

A project dependency or a prebuilt binary works too; see [how to choose an installation](<https://vaultspec.neve.md/docs/rag/installation.html#choose-what-this-environment-runs>).

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 project

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

**Command**

```bash
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**

```bash
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](<https://vaultspec.neve.md/docs/rag/service-mode.html#control-one-job>).

If a submission fails or a job shows `failed` or `cancelled`, follow the [verification guide](<https://vaultspec.neve.md/docs/rag/verification.html>).

## 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**

```bash
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](<https://vaultspec.neve.md/docs/rag/verification.html>) and [query guidance](<https://vaultspec.neve.md/docs/rag/query-craft.html>) 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**

```bash
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](<https://vaultspec.neve.md/docs/rag/query-craft.html#the-filter-surface>) for other ways to narrow a search.

## When you are finished

Stop the service when you no longer need it:

**Command**

```bash
vaultspec-rag server stop
```

Stopping the service leaves stored indexes in place. Next session, [start the service again](<https://vaultspec.neve.md/docs/rag/getting-started.html#step-2-start-the-service-and-index-your-project>). For stale indexes or configuration changes, see [reindexing](<https://vaultspec.neve.md/docs/rag/verification.html#reindexing>).

## If a step didn’t work

- [Resolve installation failures](<https://vaultspec.neve.md/docs/rag/installation.html#when-something-goes-wrong>).
- [Investigate missing or incomplete results](<https://vaultspec.neve.md/docs/rag/verification.html>).
- [Improve poor matches](<https://vaultspec.neve.md/docs/rag/query-craft.html>).

If you still need help, [report the problem](<https://github.com/nevenincs/vaultspec-rag/issues>).

## Where to go next

- [Search and index your project](<https://vaultspec.neve.md/docs/rag/search-and-index.html>)
- [Understand the architecture](<https://vaultspec.neve.md/docs/rag/architecture.html>)
- [Command-line reference](<https://vaultspec.neve.md/docs/rag/cli.html>)