CLI reference

The CLI mirrors the MCP tools one-to-one — same pipelines, same scoring, same rendering.

# Serve as an MCP server (the most common entry point)
pydocs-mcp serve /path/to/project
# --config is a global flag: it goes BEFORE the subcommand
pydocs-mcp --config ./my-pydocs.yaml serve . --no-inspect --depth 2 --workers 8
pydocs-mcp serve . --gpu            # run embedder inference on CUDA (see "GPU inference" below)

# Index only (no server) — useful for one-shot benchmark setups
pydocs-mcp index .
pydocs-mcp index . --force          # clear cache + re-index
pydocs-mcp index . --skip-project   # only index deps, not the project
pydocs-mcp index . --skip-deps      # only index the project, not its deps
pydocs-mcp index . --gpu            # index with CUDA-accelerated embeddings

# Search (mirrors the MCP `search_codebase` tool)
pydocs-mcp search "batch inference"
pydocs-mcp search "predict" --kind api -p vllm
pydocs-mcp search "handle request" -p __project__

# Navigate to a specific target (mirrors the other five MCP tools)
pydocs-mcp overview                                    # list indexed packages (get_overview)
pydocs-mcp symbol fastapi.routing.APIRouter            # class overview (get_symbol)
pydocs-mcp symbol fastapi.routing.APIRouter --depth tree
pydocs-mcp refs fastapi.routing.APIRouter.include_router --direction callers
pydocs-mcp refs requests.auth.HTTPBasicAuth --direction inherits
pydocs-mcp context fastapi.routing.APIRouter fastapi.applications.FastAPI
pydocs-mcp why "how does routing work"                 # recorded design rationale (get_why)

GPU inference (--gpu)

serve, index, and watch accept --gpu to run embedder inference on CUDA — it covers all embedders: FastEmbed and the sentence_transformers provider (single-vector dense) and PyLate (late-interaction / multi-vector). It needs no YAML change and applies to both index-time and query-time embedding.

pydocs-mcp index . --gpu     # CUDA-accelerated indexing
pydocs-mcp serve . --gpu     # CUDA for both the initial index and query-time embedding

--gpu is a runtime latency knob only: it does not change retrieval results and does not trigger a re-index — the execution device is excluded from the index-cache key, so the same .tq / fast-plaid index is shared across CPU and GPU runs. It requires the matching GPU runtime for whichever embedder you use (onnxruntime-gpu, fastembed-gpu, or a CUDA build of torch for PyLate); see INSTALL.md. With the default CPU runtimes installed, FastEmbed/ONNX fall back to CPU and only the PyLate path requires real CUDA. The benchmark runner takes the same --gpu flag.

search flags

# --kind docs     → markdown / docstring chunks only
# --kind api      → ModuleMember rows (functions, classes, signatures)
# --kind any      → both, merged + scored together (default)
# --kind decision → mined architectural-decision records
pydocs-mcp search "predict" --kind api
pydocs-mcp search "router include" --kind any --limit 20   # --limit caps multi-repo unions only

# Restrict to one package. PyPI names are normalized to the DB form
# (e.g. "Flask-Login" → "flask_login"), so either spelling works.
pydocs-mcp search "auth" -p Flask-Login

# Search only YOUR project source via the __project__ sentinel.
pydocs-mcp search "handle request" -p __project__

# Restrict by SCOPE: project | deps | all (default all).
pydocs-mcp search "retry" --scope project
pydocs-mcp search "retry" --scope deps

# Cap results for multi-repo union searches (default 10). Single-project
# result count is set by the retrieval pipeline YAML, not this flag.
pydocs-mcp search "logging" --limit 5

# Point at a different project (default is cwd).
pydocs-mcp search "celery beat" --project-dir /path/to/other/project

# Force the pure-Python fallback (debug the Rust substitution boundary).
pydocs-mcp search "tokenizer" --no-rust

search finds candidates by relevance; symbol / refs / context jump to a specific known name. symbol’s --depth accepts {summary, tree, source}; refs’ --direction accepts {callers, callees, inherits, impact, governed_by}. The deprecated lookup command still works as an alias but warns — use the task-shaped commands directly.

Shared flags

# Every subcommand accepts:
#   --cache-dir DIR       override where the .db / .tq cache bundles live
#                         (default: ~/.pydocs-mcp)
# serve / index / watch also accept:
#   --full-dep NAME       promote a dependency to full dense embedding
#                         (repeatable; fnmatch globs; merges into
#                         embedding.full_index_dependencies — see
#                         "Selective dependency embedding")
# serve and every query command also accept the multi-repo loaders
# (see "Multi-repo serving"):
#   --workspace DIR       load every pre-built .db bundle in DIR (read-only)
#   --db FILE             load a specific bundle (repeatable; read-only)
#   --project NAME        restrict a query to one loaded repo (query commands)
# why also accepts:
#   --target PATH|QNAME   decisions affecting a target — a file path (a/b.py)
#                         or a qualified name (pkg.mod); repeatable

MCP tool reference

The surface is intentionally fixed at nine task-shaped tools — they cover every workflow, and pinning them keeps MCP clients stable across server retunes (see Configuration).

Tool	Signature	Purpose
get_overview	get_overview(package, project)	Orient yourself: what is indexed and what shape a repo/package has. Empty package covers the whole workspace.
search_codebase	search_codebase(query, kind, package, scope, limit, project)	Full-text / hybrid search across indexed docs + code. kind ∈ {docs, api, any, decision}. package / scope / project are corpus-scope filters (project selects one loaded repo in a multi-repo server). limit caps multi-repo union results only; single-project result count comes from the pipeline YAML.
get_symbol	get_symbol(target, depth, project)	Navigate to a known dotted path. depth ∈ {summary, tree, source}. project resolves the target inside one loaded repo.
get_context	get_context(targets, project)	Everything needed to understand one or more symbols, packed in a single call.
get_references	get_references(target, direction, limit, project)	Traverse the reference graph. direction ∈ {callers, callees, inherits, impact, governed_by}.
get_why	get_why(query, targets, project)	Recorded architectural decisions and rationale for a topic or target.
grep	grep(pattern, path, glob, output_mode, case_insensitive, line_numbers, after_context, before_context, context, head_limit, multiline, scope, project)	Exact-string / regex search (Python re flavor) over the live source files the indexer sees. On the MCP wire the flag parameters are the literal names -i, -n, -A, -B, -C. output_mode ∈ {content, files_with_matches, count}; scope defaults to project.
glob	glob(pattern, path, head_limit, project)	Find files by name pattern (** recurses) under the project’s discovery scope; results ordered by modification time, newest first.
read_file	read_file(file_path, offset, limit, project)	Read file content with line numbers (cat -n style). Paths must resolve inside the project root or an indexed dependency root.