CLI Reference

CLI reference

Run rgr in the repository that owns the knowledge base. rgr --help and rgr <command> --help are the option-level source of truth.

Core commands

Command	Purpose
setup [--semantic]	Initialize local state, sources, agent helpers, and optional embeddings
init	Create basic local configuration only
doctor [--fix]	Check setup, index freshness, and safe repairs
preview	Parse, redact, and chunk without writing an index
ingest [--rebuild] [--batch-size N]	Index sources in resumable batches or rebuild after retrieval changes
search <query>	Return ranked cited passages
ask <query>	Return cited context without model synthesis
research <query>	Run audit-backed multi-query retrieval
audit [--unsupported]	Compare files with the index and report skipped content
bases	List root and nested monorepo knowledge bases
status	Show configuration, indexed chunks, and the latest ingestion progress
security-audit [--strict]	Check privacy and local-state posture

Sources and retrieval

rgr sources add "docs/**/*.md" "!docs/archive/**"
rgr preview --path docs --max-files 5 --max-chunks 3
rgr search "migration" --top-k 5 --context-radius 1
rgr search "migration" --context-path "Guide > Migration" --explain

Search, ask, and research support include and exclude path filters. Use --compact when consumer context is limited. Use --explain to expose reciprocal-rank-fusion contributions, retriever ranks, raw backend scores, and matched terms without changing ranking.

Resumable ingestion

rgr ingest
rgr status --json
rgr ingest --batch-size 10

The default batch contains 25 files. Ragmir atomically records per-file progress under .ragmir/storage/ after parsing, embedding, and index writes. Starting rgr ingest again resumes a compatible interrupted run. Files already committed to the index are not parsed or embedded again; pending, failed, or changed files are retried.

rgr status --json reports runId, status, mode, resumed, batchSize, lastActivityAt, the indexed chunk count, and file counts for pending, parsed, embedded, indexed, and error states. The human-readable status prints a compact version of the same progress.

rgr ingest --rebuild writes into an isolated local generation. The current healthy index remains active until the replacement table and manifest pass row-count, checksum, and duplicate-ID validation. Re-run the same command to resume an interrupted staged rebuild.

Optional local features

rgr models pull --enable
rgr ocr setup --language eng+fra
rgr chat setup --profile fast
printf '%s\n' "Non-sensitive model preload text." > /tmp/ragmir-tts-preload.txt
rgr audio /tmp/ragmir-tts-preload.txt --allow-remote-models --out .ragmir/audio/preload.wav
rgr audio ./brief.md --offline --out .ragmir/audio/brief.wav

OCR runs only for blank PDF pages. The first audio command explicitly downloads the model using non-sensitive text. The second command requires that prepared cache and performs no download. See Offline TTS for the complete preparation and privacy boundary.

Automation

rgr serve-mcp
rgr evaluate --golden .ragmir/golden.json --fail-under 0.8
rgr usage-report --days 30
rgr destroy-index --yes

Add --json to machine-readable commands. Do not parse human-readable output in automation.

Agents and maintenance

Command	Purpose
install-agent	Install native project or user-scoped agent helpers
install-skill	Refresh the canonical Ragmir skill kit
route-prompt	Classify whether a prompt should use retrieval without storing it
limits	Inspect active parser and ingestion limits
usage-report	Summarize metadata-only local access logs
destroy-index --yes	Remove generated index data explicitly

Use install-agent --force only after reviewing a conflicting same-name skill. Project scope and symlink mode are the safe defaults.

Canonical source: docs/cli-reference.md.