Skip to content

CLI Reference

Jump to bottom
Doug Gerard edited this page May 14, 2026 · 1 revision

CLI Reference

SaddleRAG ships a command-line interface (saddlerag.exe) for scripting, automation, and direct operator use. The CLI provides the same core capabilities as the MCP tools but in a form suitable for batch scripts and CI/CD pipelines.

The CLI is installed alongside the MCP server and added to the system PATH by the installer.

Global options

Option Description
--profile <name> MongoDB profile to use (overrides MongoDB.ActiveProfile)
--server <url> SaddleRAG server URL (default: http://localhost:6100)
--help Show help for any command
--version Show CLI version

saddlerag ingest

Index documentation for a library.

saddlerag ingest `
  --url https://www.pollydocs.org/ `
  --library polly `
  --version 8.2.0 `
  [--allowed-patterns "pollydocs\.org/docs/,pollydocs\.org/api/"] `
  [--excluded-patterns "pollydocs\.org/blog/"] `
  [--budget 500] `
  [--profile team] `
  [--wait]
Option Description
--url Root URL of the documentation site
--library Library identifier (short, no spaces, e.g., polly)
--version Version string (e.g., 8.2.0)
--allowed-patterns Comma-separated regex patterns for allowed URLs
--excluded-patterns Comma-separated regex patterns for excluded URLs
--budget Maximum number of pages to crawl
--profile MongoDB profile
--wait Block until the scrape job completes (default: returns immediately after queuing)

Without --wait, the command queues the scrape job and exits immediately. The scrape runs in the background in the SaddleRAGMcp service. Use saddlerag status to monitor.

saddlerag dryrun

Preview the crawl scope without indexing anything.

saddlerag dryrun `
  --url https://www.pollydocs.org/ `
  --library polly `
  --version 8.2.0

Outputs the list of URLs that would be fetched and an estimated page count. Nothing is written to the database. Useful for validating URL patterns before a full scrape.

saddlerag status

Show recent scrape job status.

# All recent jobs
saddlerag status

# Specific job
saddlerag status --job-id <jobId>

# Jobs for a specific library
saddlerag status --library polly

# Long-poll until a job completes
saddlerag status --job-id <jobId> --wait

Output includes job state, pages crawled/classified/chunked/embedded, start time, and elapsed time.

saddlerag recon

Run library reconnaissance using the local Ollama model (fallback path when a frontier LLM is not available).

saddlerag recon `
  --url https://www.pollydocs.org/ `
  --library polly `
  --version 8.2.0

Generates and persists a LibraryProfile using the configured Ollama.ReconModels model. The profile shapes subsequent indexing (URL patterns, symbol extraction, chunking).

Under normal circumstances this is invoked automatically by the start_ingest state machine. Run it manually to pre-populate a profile or override an existing one.

saddlerag scan

Scan a project's dependency files and queue scrape jobs for any undocumented dependencies.

saddlerag scan `
  --project E:\MyProject `
  [--profile team] `
  [--dry-run]
Option Description
--project Path to the project root (default: current directory)
--profile MongoDB profile
--dry-run List what would be indexed without queuing scrape jobs

scan discovers dependencies from:

  • *.csproj files (NuGet packages)
  • package.json / package-lock.json (npm packages)
  • requirements.txt / pyproject.toml (pip packages)

For each dependency, it checks whether that library and version is already in the SaddleRAG index. If not, it resolves the documentation URL from the package registry metadata and queues a scrape job.

This command is designed for CI/CD integration: run it on every dependency update and new library versions will be indexed automatically before developers need them.

saddlerag register-clients

Register SaddleRAG with installed AI tools.

saddlerag register-clients

Writes MCP configuration entries to:

  • ~/.claude.json — Claude Code
  • %APPDATA%\Claude\claude_desktop_config.json — Claude Desktop
  • VS Code user settings.json — VS Code Copilot MCP
  • GitHub Copilot CLI config

Also installs the SaddleRAG skill file for Claude Code (.claude/saddlerag-first.md) that instructs Claude to always query SaddleRAG before answering questions about indexed libraries.

Run this after installation or after moving the server to a different port.

saddlerag unregister-clients

Remove SaddleRAG from all AI tool configurations.

saddlerag unregister-clients

Reverses all changes made by register-clients.

saddlerag search

Search the indexed documentation from the command line.

saddlerag search "retry policy configuration" `
  [--library polly] `
  [--version 8.2.0] `
  [--category ApiReference] `
  [--results 10] `
  [--profile team]

Outputs formatted search results to the terminal. Useful for testing search quality and verifying that a library is correctly indexed.

saddlerag list

List indexed libraries and their versions.

saddlerag list [--profile team]

saddlerag health

Show library health diagnostics.

saddlerag health --library polly [--version 8.2.0] [--profile team]

Equivalent to the get_library_health MCP tool. Shows chunk counts, category distribution, and suspect markers.

CI/CD integration example

# .github/workflows/index-docs.yml
name: Index documentation

on:
  push:
    paths:
      - '**/*.csproj'
      - '**/package.json'
      - '**/requirements.txt'

jobs:
  index:
    runs-on: [self-hosted, saddlerag]  # runner with SaddleRAG installed
    steps:
      - uses: actions/checkout@v4
      - name: Scan and index new dependencies
        run: saddlerag scan --project . --profile team --wait

This workflow triggers whenever dependency files change, automatically indexing documentation for newly added or updated libraries into the team's shared SaddleRAG index.

Clone this wiki locally