> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/poweroutlet2/openground/llms.txt
> Use this file to discover all available pages before exploring further.

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

<CodeGroup>
  ```bash uv (Recommended) theme={null}
  uv tool install openground
  ```

  ```bash pip theme={null}
  pip install openground
  ```
</CodeGroup>

<Tip>
  The default package includes sentence-transformers with automatic GPU/MPS/CPU support. For a lighter install, see [Installation Options](/installation).
</Tip>

## Step 2: Add Documentation

Let's add the FastAPI documentation as an example:

```bash theme={null}
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

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

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

```bash theme={null}
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)
```

<Tip>
  OpenGround uses **hybrid search** that combines semantic understanding with keyword matching for the best results.
</Tip>

## Step 4: List Your Libraries

View all documentation you've added:

```bash theme={null}
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:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    openground install-mcp --claude-code
    ```

    Restart Claude Code and you're ready! Your AI assistant can now search FastAPI documentation automatically.
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    openground install-mcp --cursor
    ```

    Restart Cursor and you're ready!
  </Tab>

  <Tab title="OpenCode">
    ```bash theme={null}
    openground install-mcp --opencode
    ```

    Restart OpenCode and you're ready!
  </Tab>

  <Tab title="Other">
    ```bash theme={null}
    openground install-mcp
    ```

    Copy the JSON configuration shown and add it to your agent's MCP settings.
  </Tab>
</Tabs>

## What's Next?

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

<CardGroup cols={2}>
  <Card title="Add More Sources" icon="plus" href="/guides/add-from-git">
    Add documentation from git repos, sitemaps, or local files
  </Card>

  <Card title="Configure Settings" icon="gear" href="/usage/configuration">
    Customize chunk size, embedding models, and more
  </Card>

  <Card title="MCP Integration" icon="plug" href="/integration/mcp-overview">
    Deep dive into AI agent integration
  </Card>

  <Card title="Advanced Search" icon="magnifying-glass" href="/advanced/hybrid-search">
    Learn about hybrid search and tuning
  </Card>
</CardGroup>

## Common Use Cases

<Accordion title="Add documentation from a website sitemap">
  ```bash theme={null}
  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.
</Accordion>

<Accordion title="Add local documentation">
  ```bash theme={null}
  openground add my-project \
    --source ~/projects/my-project/docs \
    -y
  ```

  Indexes documentation from your local project. Great for internal or private docs.
</Accordion>

<Accordion title="Query across multiple libraries">
  ```bash theme={null}
  openground query "async database queries" --top-k 20
  ```

  Omit the `--library` flag to search across all installed documentation.
</Accordion>

<Accordion title="Update documentation when it changes">
  ```bash theme={null}
  openground update fastapi --version 0.115.6
  ```

  OpenGround intelligently updates only what changed using content hashes.
</Accordion>

## Example: Complete Workflow

Here's a complete workflow for a Python developer:

<Steps>
  <Step title="Install OpenGround">
    ```bash theme={null}
    uv tool install openground
    ```
  </Step>

  <Step title="Add Python Framework Documentation">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Install MCP for Claude Code">
    ```bash theme={null}
    openground install-mcp --claude-code
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Troubleshooting

<Accordion title="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`
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="No results from query">
  Check that the library was added successfully.

  **Solution:**

  ```bash theme={null}
  # 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>
  ```
</Accordion>

## Next Steps

Now that you have the basics, explore:

* [Core Concepts](/concepts/architecture) - Understand how OpenGround works
* [Sources Guide](/guides/sources-files) - Learn about sources.json and reusable configurations
* [CLI Reference](/cli/add) - Complete command reference
* [MCP Server](/mcp/search-documents) - API reference for AI agent integration

<Note>
  Need help? Check the [troubleshooting guides](/usage/configuration#troubleshooting) or [open an issue on GitHub](https://github.com/poweroutlet2/openground/issues).
</Note>