Managing Libraries

OpenGround provides commands to manage your indexed documentation libraries, including listing available libraries, viewing statistics, and removing libraries you no longer need.

List Libraries

View all libraries stored in your LanceDB database:

openground list-libraries

Alias: openground ls

Output Format

Results are displayed in a formatted table:

┌─────────────────────────────────────────────────────────────┐
│ Available Libraries                                         │
├──────────────┬──────────────────────────────────────────────┤
│ Library      │ Versions                                     │
├──────────────┼──────────────────────────────────────────────┤
│ nextjs       │ latest, v13.0.0, v14.0.0                     │
│ openground   │ latest                                       │
│ react        │ latest, v18.0.0, v18.2.0                     │
└──────────────┴──────────────────────────────────────────────┘

This shows libraries that have been embedded into LanceDB. To see raw extracted data, use openground list-raw-libraries.

List Raw Libraries

View libraries in the raw data directory (extracted but possibly not yet embedded):

openground list-raw-libraries

Output Format

Available libraries in raw_data:
nextjs: latest, v13.0.0, v14.0.0
openground: latest
react: latest, v18.0.0

What's the difference between list-libraries and list-raw-libraries?

list-libraries: Shows libraries in LanceDB (embedded and searchable)
list-raw-libraries: Shows libraries in raw_data directory (extracted JSON files)

Normally these match, but they can differ if:

Extraction completed but embedding was interrupted
You manually deleted the database
Embedding is in progress

Programmatic Library Listing

List libraries from Python code:

from pathlib import Path
from openground.query import list_libraries, list_libraries_with_versions

# Get list of library names
db_path = Path.home() / ".local/share/openground/lancedb"
libraries = list_libraries(db_path=db_path, table_name="documents")
print(libraries)  # ['nextjs', 'openground', 'react']

# Get libraries with versions
libs_with_versions = list_libraries_with_versions(
    db_path=db_path,
    table_name="documents"
)
print(libs_with_versions)
# {
#   'nextjs': ['latest', 'v13.0.0', 'v14.0.0'],
#   'openground': ['latest'],
#   'react': ['latest', 'v18.0.0', 'v18.2.0']
# }

# Search libraries by name
libs_with_versions = list_libraries_with_versions(
    db_path=db_path,
    table_name="documents",
    search_term="next"  # Case-insensitive search
)
print(libs_with_versions)  # {'nextjs': ['latest', 'v13.0.0', 'v14.0.0']}

Remove Libraries

Delete a library version from LanceDB:

openground remove <library-name> --version <version>

Alias: openground rm

Remove Options

library_name

string

required

Name of the library to remove

--version

string

required

Version of the library to remove

--yes

boolean

Skip confirmation prompts

Remove Examples

# Remove with confirmation
openground remove react --version v18.0.0

# Remove without confirmation
openground rm nextjs --version latest --yes

Confirmation Dialog

By default, OpenGround shows library details and asks for confirmation:

Library: react
Version: v18.0.0
  Chunks: 1250
  Pages:  180
  Sample titles: Getting Started, Hooks API Reference, Component API Reference

Are you sure you want to delete this library version? [y/N]: y

Deleted 1250 chunks for library 'react' version 'v18.0.0'.

Also delete raw files at ~/.local/share/openground/raw_data/react/v18.0.0? [y/N]: y
Deleted raw library files at ~/.local/share/openground/raw_data/react/v18.0.0.

Removing a library is permanent and cannot be undone. You’ll need to re-extract and re-embed the library to restore it.

Library Statistics

Get detailed statistics for a specific library version:

from pathlib import Path
from openground.query import get_library_stats

stats = get_library_stats(
    library_name="react",
    version="latest",
    db_path=Path.home() / ".local/share/openground/lancedb",
    table_name="documents"
)

if stats:
    print(f"Library: {stats['library_name']}")
    print(f"Version: {stats['version']}")
    print(f"Chunks: {stats['chunk_count']}")
    print(f"Pages: {stats['unique_urls']}")
    print(f"Sample titles: {', '.join(stats['titles'])}")
else:
    print("Library not found")

Stats Output

{
    'library_name': 'react',
    'version': 'latest',
    'chunk_count': 1250,      # Total chunks in LanceDB
    'unique_urls': 180,       # Number of unique pages
    'titles': [               # Sample page titles (up to 5)
        'Getting Started',
        'Hooks API Reference',
        'Component API Reference',
        'React Router Guide',
        'Performance Optimization'
    ]
}

Global Statistics

View overall OpenGround statistics:

openground stats show

Stats Output

Openground Statistics
==================================================
Libraries: 3
Total chunks: 2580

Tool calls:
  get_full_content: 45
  list_libraries: 12
  search: 89

What are tool calls?

Tool calls are tracked when using OpenGround through MCP (Model Context Protocol) integration with AI editors like Claude Code, Cursor, or OpenCode. Each time the AI uses an OpenGround tool, it’s counted here.

Reset Statistics

Clear tool call statistics:

openground stats reset

# Skip confirmation
openground stats reset --yes

This only resets tool call counts, not library data. Your libraries and embeddings remain intact.

Delete All Data

OpenGround provides nuke commands to delete data:

Delete Everything

Delete both raw data and embeddings:

openground nuke all

Delete Only Raw Data

Delete extracted JSON files but keep embeddings:

openground nuke raw_data

Delete Only Embeddings

Delete LanceDB but keep raw extracted files:

openground nuke embeddings

Nuke Examples

# Show what will be deleted (confirmation required by default)
openground nuke all

# Delete without confirmation
openground nuke all --yes

# Delete only embeddings
openground nuke embeddings --yes

Nuke Confirmation

The command shows a summary before deleting:

This will permanently delete ALL data:
  • Raw data: 3 libraries in ~/.local/share/openground/raw_data
  • Embeddings: 3 libraries in ~/.local/share/openground/lancedb

Tip: Run 'openground list-raw-libraries' and 'openground list-libraries' 
to see what will be deleted.

Are you sure you want to delete ALL data? This cannot be undone! [y/N]:

PERMANENT DELETION: nuke commands permanently delete data and cannot be undone. Make sure you have backups or can re-extract your libraries.

When should I use nuke commands?

Use nuke commands when:

Starting fresh with a new configuration
Clearing disk space
Switching embedding models (requires re-embedding)
Troubleshooting database corruption
Testing or development workflows

Do not use if you want to keep your libraries and just update them (use openground update instead).

Programmatic Deletion

Delete libraries from Python:

from pathlib import Path
from openground.query import delete_library, delete_urls

# Delete entire library version
db_path = Path.home() / ".local/share/openground/lancedb"
deleted_count = delete_library(
    library_name="react",
    version="v18.0.0",
    db_path=db_path,
    table_name="documents"
)
print(f"Deleted {deleted_count} chunks")

# Delete specific URLs
deleted_count = delete_urls(
    urls=[
        "https://react.dev/learn/getting-started",
        "https://react.dev/reference/hooks"
    ],
    library_name="react",
    version="latest",
    db_path=db_path,
    table_name="documents"
)
print(f"Deleted {deleted_count} chunks")

Storage Locations

Understanding where data is stored:

Linux/macOS
Windows

# Raw data (extracted JSON)
~/.local/share/openground/raw_data/

# LanceDB embeddings
~/.local/share/openground/lancedb/

# Configuration
~/.config/openground/config.json

# User sources
~/.openground/sources.json

# Raw data (extracted JSON)
%LOCALAPPDATA%\openground\raw_data\

# LanceDB embeddings
%LOCALAPPDATA%\openground\lancedb\

# Configuration
%LOCALAPPDATA%\openground\config.json

# User sources
%USERPROFILE%\.openground\sources.json

You can customize storage locations using the config file. See Configuration for details.

Best Practices

Regular Cleanup

Periodically remove old versions you no longer need:

openground rm mylib --version v1.0.0 --yes

Version Management

Keep only versions you actively use:

# Keep latest and current production
openground ls
openground rm mylib --version v2.0.0

Monitor Disk Usage

Check storage usage regularly:

du -sh ~/.local/share/openground

Backup Before Nuke

Back up important libraries before mass deletion:

cp -r ~/.local/share/openground ~/backup/

Get Started

Core Concepts

Adding Documentation

AI Agent Integration

Usage

Advanced

List Libraries

Output Format

List Raw Libraries

Output Format

Programmatic Library Listing

Remove Libraries

Remove Options

Remove Examples

Confirmation Dialog

Library Statistics

Stats Output

Global Statistics

Stats Output

Reset Statistics

Delete All Data

Delete Everything

Delete Only Raw Data

Delete Only Embeddings

Nuke Examples

Nuke Confirmation

Programmatic Deletion

Storage Locations

Best Practices

Regular Cleanup

Version Management

Monitor Disk Usage

Backup Before Nuke

Next Steps

Querying

Updating

Get Started

Core Concepts

Adding Documentation

AI Agent Integration

Usage

Advanced

​List Libraries

​Output Format

​List Raw Libraries

​Output Format

​Programmatic Library Listing

​Remove Libraries

​Remove Options

​Remove Examples

​Confirmation Dialog

​Library Statistics

​Stats Output

​Global Statistics

​Stats Output

​Reset Statistics

​Delete All Data

​Delete Everything

​Delete Only Raw Data

​Delete Only Embeddings

​Nuke Examples

​Nuke Confirmation

​Programmatic Deletion

​Storage Locations

​Best Practices

Regular Cleanup

Version Management

Monitor Disk Usage

Backup Before Nuke

​Next Steps

Querying

Updating

List Libraries

Output Format

List Raw Libraries

Output Format

Programmatic Library Listing

Remove Libraries

Remove Options

Remove Examples

Confirmation Dialog

Library Statistics

Stats Output

Global Statistics

Stats Output

Reset Statistics

Delete All Data

Delete Everything

Delete Only Raw Data

Delete Only Embeddings

Nuke Examples

Nuke Confirmation

Programmatic Deletion

Storage Locations

Best Practices

Next Steps