Getting started

This guide indexes a git repository on your machine and searches it, first yourself and then through an agent.

Install gv and sign in.

gv is the Grepvine CLI. It creates organizations and indexes, and syncs directories, which the SDKs don’t do.

curl -fsSL https://get.grepvine.ai/install.sh | sh
gv login

gv login opens a browser where you approve the sign-in, then saves an API key for gv. CLI has the other ways to install it.

Create an organization.

An organization owns indexes and has members. Its name is global and shares a namespace with user names, so pick one of your own and use it wherever this guide says acme:

gv org create acme

You’re the organization’s owner. Concepts explains the roles you can give its members.

Create an index.

gv index create acme/myapp \
  --description 'Source of myapp, mirrored from its main branch. Keys are paths from the repository root.'

Agents read the description to choose an index, so say what it holds. A new index is ready within a moment. To wait for it:

until gv index info acme/myapp --json | grep -q '"state":"ready"'; do sleep 1; done

Sync a directory.

gv sync makes the index mirror a directory. Preview it, then run it:

cd ~/src/myapp
gv sync . acme/myapp --dry-run
gv sync . acme/myapp

gv: synced . to acme/myapp: 1284 uploaded, 0 deleted, 0 skipped (commit 4f9c2ab)

In a git repository, gv sync uploads the tracked files and records the commit in the index’s git.commit tag. Uncommitted changes to tracked files stop it before it writes anything. After your next commit, run the same command again: it uploads the files that changed and deletes the documents of files you removed.

Search it.

The SDKs and curl need an API key in GREPVINE_API_KEY. Create one with gv:

export GREPVINE_API_KEY=$(gv key create getting-started)

This search finds every TODO and FIXME under src/, with the two lines after each:

Python

import os
import grepvine
from grepvine.models import QueryRequest

client = grepvine.Client(api_key=os.environ["GREPVINE_API_KEY"])

query = QueryRequest(pattern=r"(TODO|FIXME)\b", filter_="path STARTSWITH 'src/'", lines_after=2)
for hit in grepvine.paginate(client.search.query, organization="acme", index="myapp", body=query):
    print(f"{hit.key}:{hit.line_number}: {hit.text}")

TypeScript

import { GrepvineClient, paginate } from "@grepvine/sdk";

const client = new GrepvineClient({ apiKey: process.env.GREPVINE_API_KEY! });

for await (const hit of paginate(client.search.query, {
  organization: "acme",
  index: "myapp",
  pattern: String.raw`(TODO|FIXME)\b`,
  filter: "path STARTSWITH 'src/'",
  lines_after: 2,
})) {
  console.log(`${hit.key}:${hit.line_number}: ${hit.text}`);
}

CLI

gv search acme/myapp '(TODO|FIXME)\b' --filter "path STARTSWITH 'src/'" -A 2

curl

curl -X POST "https://api.grepvine.ai/v1/organizations/acme/indexes/myapp/query" \
  -H "Authorization: Bearer $GREPVINE_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{"pattern": "(TODO|FIXME)\\b", "filter": "path STARTSWITH 'src/'", "lines_after": 2}
EOF

Install the SDKs with pip install grepvine or npm install @grepvine/sdk. Every search returns every match, sorted by key and line. Searching covers patterns, filters and context.

Let an agent search it.

Grepvine’s MCP server gives an agent the same index. To connect Claude Code, with the key from the previous step:

claude mcp add --transport http --scope user grepvine https://api.grepvine.ai/mcp \
  --header "Authorization: Bearer $GREPVINE_API_KEY"

Then ask a question that needs every occurrence:

claude "Using the acme/myapp Grepvine index, find every place we retry an HTTP request and list the retry limits each one uses."

Claude reads the index’s description with list_indexes, searches with search, and reads files around the matches with get_document. It asks before each tool call, unless you allow the tools in its settings.

MCP server covers Claude Desktop, DeepAgents and other clients. For an agent that works in your terminal, the agent skill teaches it to use gv instead.

Next steps.

• Keep the index current. Best practices has a GitHub Actions workflow that runs gv sync on every push.
• Limit what agents can do. Security shows how to give an agent a read-only key.
• Learn the model. Concepts and guarantees explain indexes, documents, queries and what Grepvine promises about them.