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
team sync	Safely fast-forward the current Git upstream and refresh the local index
team snapshot, team compare	Run advanced privacy-bounded drift diagnostics
upgrade [--check]	Inspect compatibility or safely rebuild and refresh managed helpers
security-audit [--strict]	Check privacy and local-state posture

Sources and retrieval

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

sources add accepts paths, globs, and ! exclusions. Search, ask, and research support include, exclude, and structural-context path filters. Use --compact when consumer context is limited. Search and ask accept --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. After each batch, Ragmir atomically records per-file state and the current manifest under .ragmir/storage/. 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.

Fast inventory reuses a private SHA-256 only while file identity and high-resolution metadata still match, with periodic full verification. Set sourceFingerprintMode: "strict" to recalculate every hash. A committed batch atomically replaces the changed source's chunks.

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. Older generated tables remain available for searches that already opened them; rgr destroy-index --yes removes all generated index storage.

Team synchronization

rgr team sync

Run this after reviewed source changes merge into the current branch upstream. That upstream is the declared authority, and Git remains the place where the team reviews differences. team sync fetches only that branch, fast-forwards only a clean non-divergent history with no local-only commits, then ingests changed sources incrementally. Git authentication is non-interactive and each command is bounded.

Result	Meaning
current	The checked-out sources and private local index already match upstream.
updated	A safe fast-forward and incremental ingest completed.
Needs action	Git history and the active index were preserved; follow the one recommended action.

A dirty, ahead, diverged, detached, no-upstream, fetch, or ingestion failure never rewrites history or deletes the last valid index. Use --no-pull to fetch and compare without updating the branch, --no-fetch for an explicitly offline run, --check to inspect without changing Git or the index, --strict to return exit code 1 when synchronization needs action, --json for typed output, and --timeout-ms to bound Git work.

Advanced: exact drift or a non-Git authority

Snapshots are not part of the normal Git workflow. Use them for a non-Git authority or a specific per-file comparison:

rgr team snapshot --label local --output .ragmir/team/local.json
rgr team compare .ragmir/team/local.json --local-label peer

Snapshots contain relative paths, checksums, readiness, version, and index settings, never source text or absolute project paths. Existing v2.19 snapshots remain compatible.

Safe upgrades

rgr upgrade --check
rgr upgrade

The check reports current, index-required, rebuild-required, or repair-required. The upgrade refreshes managed helpers and stages any required replacement in an isolated generation. Only a validated replacement activates, so failed or interrupted rebuilds leave the previous valid index untouched and can resume. Older configs receive current safe defaults. ready covers upgrade and retrieval continuity; privacyCompliant and advisory report independent security follow-ups. Address advisories with rgr security-audit instead of rebuilding a healthy index.

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 --lang en --allow-remote-models --out .ragmir/audio/preload.wav
rgr audio ./brief.md --lang en --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.