docs-search.md

title	Documentation search (`volcano docs`)
description	Search and read the official Volcano documentation from your terminal with volcano docs, cached locally for offline use.

volcano docs fetches the official Volcano documentation into a local cache and lets you search and read it from your terminal — offline, and without leaving your workflow. It is designed for both humans and AI agents: --json output is a stable, versioned contract so an agent driving the CLI can look things up and validate its assumptions against the docs.

Commands

# Fetch or refresh the local cache from the source repository
volcano docs sync

# Search the docs (ranked, with snippets)
volcano docs search "reset password email"
volcano docs search "service key" --topic authentication -n 5

# Read a whole document, or a single section by its #anchor
volcano docs get authentication/password-reset.md
volcano docs get "authentication/password-reset.md#how-it-works"

# List the available documents
volcano docs list --topic storage

Reads (search, get, list) bootstrap the cache automatically on first use. After that they never touch the network; run volcano docs sync to refresh. Pass --offline to guarantee no network access (a missing cache then errors).

MCP server mode (for agents)

volcano docs mcp runs a long-lived Model Context Protocol server over stdio, exposing the docs as agent tools. Unlike the one-shot subcommands (which rebuild the ~6.7 MB BM25 index on every call), the server builds the index once and keeps it resident, so an agent doing repeated search→read loops reuses a warm index.

Tools: docs_search (query, optional topic, limit), docs_get (id = path or path#anchor), and docs_list (optional topic). Each tool returns the same versioned envelope as --json, both as text content and as structuredContent; domain failures come back as a tool result with isError: true and a DOCS_* code, while malformed calls use JSON-RPC errors. stdout carries only JSON-RPC frames; diagnostics go to stderr.

Register it with an MCP client, e.g. Claude Code:

{
  "mcpServers": {
    "volcano-docs": { "command": "volcano", "args": ["docs", "mcp"] }
  }
}

The index is rebuilt automatically if an external volcano docs sync publishes a new snapshot while the server is running.

How search works

The corpus is parsed into heading-delimited sections. Each search builds a small in-memory BM25 index over those sections with boosts for titles, headings, paths, exact phrases, and technical tokens (identifiers, flags, CLI commands), then returns the best-matching sections with a snippet and source line range. The CLI docs section (the cli topic) gets a ranking boost, so an otherwise comparable CLI match sorts above the broader product/platform docs; a substantially stronger product match can still rank higher. No index is persisted and no external services are used.

JSON output for agents

Every command supports --json, emitting a single versioned envelope on stdout (progress and warnings go to stderr):

{
  "schema_version": 1,
  "command": "search",
  "source": {
    "provider": "github",
    "repository": "Kong/volcano-docs",
    "ref": "main",
    "path": "content",
    "resolved_commit": "…"
  },
  "cache": { "key": "…", "synced_at": "…", "checked_at": "…", "stale": false, "offline": false },
  "data": [
    {
      "id": "authentication/password-reset.md#how-it-works",
      "rank": 1,
      "score": 12.34,
      "path": "authentication/password-reset.md",
      "topic": "authentication",
      "title": "Password Reset",
      "heading_path": ["Password Reset", "How It Works"],
      "anchor": "how-it-works",
      "line_start": 20,
      "line_end": 31,
      "snippet": "…",
      "matched_terms": ["reset", "password"]
    }
  ]
}

A result id (path#anchor) can be passed straight to volcano docs get to read that section. Errors use the same envelope with an error object (code, message) and a nonzero exit status. Codes include DOCS_CACHE_MISSING, DOCS_SOURCE_UNAVAILABLE, DOCS_INVALID_SOURCE, DOCS_NOT_FOUND, DOCS_INVALID_ID, and DOCS_SYNC_INCOMPLETE.

Configuring the source

The documentation source defaults to the content/ directory of the public Kong/volcano-docs repository on main — the full Volcano documentation corpus, including the CLI docs under content/cli — and needs no authentication. Override the source per invocation or via the environment; precedence is flags → environment → config → defaults:

Field	Flag	Environment
repository	--repo	VOLCANO_DOCS_REPO
git ref	--ref	VOLCANO_DOCS_REF
subdir	--path	VOLCANO_DOCS_PATH

To restrict a search to just the CLI docs, use --topic cli:

volcano docs search "docs search" --topic cli

Each source is cached separately. Note that volcano <command> --help is the authoritative, always-current reference for command syntax and flags; the docs corpus complements it with conceptual guides and product context. For private source repositories, set GITHUB_TOKEN; it is sent only to api.github.com and never to any other host.