Quickstart

Get started with OpenGround in 5 minutes

Quickstart

Get OpenGround up and running in 5 minutes. This guide will take you from installation to your first documentation search.

Prerequisites

• Python 3.10, 3.11, or 3.12
• pip or uv package manager

Step 1: Install OpenGround

Install OpenGround using your preferred package manager:

uv (Recommended)

uv tool install openground

The default package includes sentence-transformers with automatic GPU/MPS/CPU support. For a lighter install, see Installation Options.

Step 2: Add Documentation

Let’s add the FastAPI documentation as an example:

openground add fastapi \
  --source https://github.com/tiangolo/fastapi.git \
  --docs-path docs/ \
  --version 0.115.5 \
  -y

This command:

• Clones the FastAPI repository at version 0.115.5
• Extracts documentation from the docs/ folder
• Chunks the text into manageable pieces
• Generates embeddings using a local model
• Stores everything in a local LanceDB database

The first time you add documentation, OpenGround will download the embedding model (~200MB for BGE-small-en-v1.5). This only happens once.

Expected output:

Extraction complete: 150 pages extracted to ~/.openground/raw_data/fastapi/0.115.5
Chunking documents: 100%|████████████████████| 150/150 [00:02<00:00]
Generating embeddings: 100%|█████████████████| 800/800 [00:15<00:00]
Inserting 800 chunks into LanceDB...
Embedding complete: Library fastapi (0.115.5) added to LanceDB.

Step 3: Search Documentation

Now you can search the documentation:

openground query "How do I create a route with path parameters?" \
  --library fastapi \
  --version 0.115.5

Example output:

Found 10 matches.
1. **Path Parameters**: "You can declare path parameters in your path operation function parameters..."
   (Source: https://fastapi.tiangolo.com/tutorial/path-params/, Version: 0.115.5)
   
2. **Path Parameters with Types**: "You can declare the type of a path parameter in the function..."
   (Source: https://fastapi.tiangolo.com/tutorial/path-params/#path-parameters-with-types, Version: 0.115.5)

OpenGround uses hybrid search that combines semantic understanding with keyword matching for the best results.

Step 4: List Your Libraries

View all documentation you’ve added:

openground list

Output:

Available Libraries
┌──────────┬───────────┐
│ Library  │ Versions  │
├──────────┼───────────┤
│ fastapi  │ 0.115.5   │
└──────────┴───────────┘

Step 5: Connect to Your AI Agent

OpenGround really shines when connected to AI coding assistants. Install the MCP server:

Claude Code

openground install-mcp --claude-code

Restart Claude Code and you’re ready! Your AI assistant can now search FastAPI documentation automatically.

Cursor

openground install-mcp --cursor

Restart Cursor and you’re ready!

OpenCode

openground install-mcp --opencode

Restart OpenCode and you’re ready!

Other

openground install-mcp

Copy the JSON configuration shown and add it to your agent’s MCP settings.

What’s Next?

You now have OpenGround installed and working! Here are some next steps:

Add More Sources

Add documentation from git repos, sitemaps, or local files

Configure Settings

Customize chunk size, embedding models, and more

MCP Integration

Deep dive into AI agent integration

Advanced Search

Learn about hybrid search and tuning

Common Use Cases

Add documentation from a website sitemap

openground add numpy \
  --source https://numpy.org/doc/stable/sitemap.xml \
  --filter-keyword reference \
  -y

This extracts all pages containing “reference” in the URL from NumPy’s documentation.

Add local documentation

openground add my-project \
  --source ~/projects/my-project/docs \
  -y

Indexes documentation from your local project. Great for internal or private docs.

Query across multiple libraries

openground query "async database queries" --top-k 20

Omit the --library flag to search across all installed documentation.

Update documentation when it changes

openground update fastapi --version 0.115.6

OpenGround intelligently updates only what changed using content hashes.

Example: Complete Workflow

Here’s a complete workflow for a Python developer:

1. Install OpenGround

   uv tool install openground
   
2. Add Python Framework Documentation

   # FastAPI
   openground add fastapi \
     --source https://github.com/tiangolo/fastapi.git \
     --docs-path docs/ \
     --version 0.115.5 \
     -y
   
   # Pydantic
   openground add pydantic \
     --source https://github.com/pydantic/pydantic.git \
     --docs-path docs/ \
     --version v2.9.0 \
     -y
   
   # SQLAlchemy
   openground add sqlalchemy \
     --source https://docs.sqlalchemy.org/sitemap.xml \
     --filter-keyword /en/20/ \
     -y
   
3. Install MCP for Claude Code

   openground install-mcp --claude-code
   
4. Use in Your AI Assistant

   In Claude Code, ask:

   “How do I create a Pydantic model with validation?”

   Claude will automatically search your local Pydantic documentation and provide accurate answers with sources.

Troubleshooting

Command not found: openground

The package isn’t in your PATH.

Solution:

• If using uv: Run uv tool update-shell and restart your terminal
• If using pip: Ensure pip’s bin directory is in your PATH
• Try running with full path: python -m openground

Extraction is slow

First extraction downloads the embedding model and clones repositories.

This is normal:

• Embedding model download: ~200MB, happens once
• Git clone: depends on repo size
• Subsequent additions are faster

To speed up:

• Use --docs-path to extract only specific folders
• Use faster internet connection for initial setup
• Consider fastembed backend for faster CPU embeddings

No results from query

Check that the library was added successfully.

Solution:

# List libraries
openground list

# If missing, add it
openground add library-name --source <url> -y

# Check the version matches
openground query "your query" --library library-name --version <version>

Next Steps

Now that you have the basics, explore:

• Core Concepts - Understand how OpenGround works
• Sources Guide - Learn about sources.json and reusable configurations
• CLI Reference - Complete command reference
• MCP Server - API reference for AI agent integration

Need help? Check the troubleshooting guides or open an issue on GitHub.