CLI: commands, flags, exit codes

The full ragraf command-line reference: install, ensure, query, reindex, selftest, global flag order and exit codes.

Entry point #

Shell

ragraf -p config/mycorpus.yaml <command> [args]
# or without installing the package:
python tools/ragraf.py -p config/mycorpus.yaml <command>

The tools/ragraf.py wrapper adds src/ to sys.path itself — it works from a repository clone without pip install.

Flag order is a frequent mistake: the global --project/-p and --json go before the subcommand:

Shell

ragraf -p cfg.yaml --json query search "threshold"     # ✓
ragraf query search "threshold" -p cfg.yaml            # ✗ unrecognized argument

The exception is ensure: it has its own --json, placed after (a fixed contract, not an oversight):

Shell

ragraf ensure /path/to/project --json              # ✓

Top-level commands #

Command	Purpose
`init <dir>`	create a corpus configuration for a directory (sensible defaults replace interactive prompts)
`ensure <dir>`	idempotent: find/create the corpus, check freshness, reindex on divergence
`index` / `reindex`	full revision rebuild; the drift ledger is archived into the report
`status`	summary: revision, capability, sizes, drift
`selftest`	environment component report (9 mandatory + joern/java optional). Always exit 0 — a report, not a gate; read the report body
`query <operation>`	any facade operation: `search`, `symbol`, `callers`, `impact`, `slice`, `schema`, `write_check`, `routes`, `policy_trace`, `drift_report`, `usage_stats`, …
`serve-mcp`	start the MCP server (normally launched by the agent, not a human)
`admin`	start the local admin panel (127.0.0.1:8777)

Examples from real practice #

Shell

# find a symbol and its incoming calls
ragraf -p cfg.yaml query symbol --name corpus_hash
ragraf -p cfg.yaml query callers --name z_agr_audit_log --mode all

# hybrid search with immediate fragment text (no second call)
ragraf -p cfg.yaml query search "reindex threshold" --with-text --top 8

# validate the write plan BEFORE executing SQL
ragraf -p cfg.yaml query write_check --table z_agr_payments --columns "amount,AuthorUserID"
# → column AuthorUserID not found; nearest: InitiatorID, UpdatedBy

# the "what changed in the knowledge" report after edits
ragraf -p cfg.yaml query drift_report

Output formats #

--json — the machine-readable envelope (identical to MCP's; see operations).
without the flag — compact human-readable output; no tables are drawn, facts are listed line by line with path:line.

JSON is pipe-ready: ragraf -p cfg --json query symbol --name X | jq '.result[] | .path'. The installer and selftest wrappers parse exactly --json (the installer refactor added timeouts and pipe-deadlock protection — see INSTALLER-REFACTOR-NOTES in the repository).

Exit codes #

Code	Meaning	Typical cause
0	success (for `selftest` — "report produced", even if components are missing)	—
1	argument/corpus error	flag after the subcommand; no config; corpus not found
2	internal error	corrupted store; a bug (report to GitHub Issues with the traceback)
3	operation impossible in this state	`slice` under `capability=degraded`; refusal with an explicit reason

Code 3 is not "nothing found". "Not found" is a successful answer with an empty result and declared limits. The distinction is fundamental: absence of a fact and impossibility of an operation are different events (anti-requirement #4).

Environment variables #

Variable	Effect
`RAGRAF_MODEL_CACHE`	embedding model cache directory (default `~/.ragraf/models`)
`RAGRAF_JOERN_HEAP_GB`	heap for the Joern server (large corpora)
`RAGRAF_DEBUG`	verbose tracebacks to stderr
`RAGRAF_ADMIN_TOKEN`	admin-panel mutation token (otherwise printed to the console at startup)

Windows notes #

PowerShell 7.6+ verified; Windows PowerShell 5.1 unverified.
Paths with spaces — quote them; config glob patterns — forward slash / (backslashes work, but / is canonical).
Known installer gap: glob case-sensitivity on Windows is recorded in the defect register (E-01) — workaround: normalize paths in the config.