Repository navigation
05 CLI Reference
Exact surface of ragraf (console command after pip install -e ., or python tools/ragraf.py, or scripts/ragraf.ps1). Verified against src/ragraf/cli.py at revision df7c1be.
ragraf [--project <cfg>] [--json] <command> [command args]
| Rule | Detail |
|---|---|
| Global flags go BEFORE the subcommand |
ragraf -p cfg --json query search "x" ✔ · ragraf query search "x" -p cfg ✘ |
Exception: ensure has its own --json |
ragraf ensure <dir> --json (after the subcommand) |
--project/-p |
path to the corpus config. Not required for init, catalog, ensure (they resolve/create it); required elsewhere — a clear hint is printed instead of a traceback when missing |
--json |
machine-readable output (the envelope, unchanged) |
--version |
ragraf 0.1.0 |
| Code | Meaning |
|---|---|
| 0 | success — including «not found» (found=false in the payload) |
| 1 | runtime error |
| 2 | usage error (bad args, missing config) |
| 3 |
layer refusal — the operation cannot run right now (e.g. slice at capability≠full). Not «empty result», not «broken tool» |
(The constant EXIT_NOT_FOUND remains as an alias of 3 for old external callers; its meaning is «layer refused».)
The only command that works without --project (it creates one). Inspects the directory and derives languages, includes, excludes, thresholds. Prints the config path.
ragraf init C:\work\myproject [--name <effort>] [--config <path>] [--force]
| Flag | Meaning |
|---|---|
--name |
registry category (default: directory name) |
--config |
where to write the config (default: config/) |
--force |
overwrite an existing config |
After
init, reviewinclude/exclude— especially secret-bearing paths (config.local.*,.env, keys). Then:register+index, or justensure.
One-call readiness: find the corpus by project directory → rebuild if stale → create if unknown. Root defaults to ..
| Flag | Meaning |
|---|---|
--no-create |
do not create a corpus for an unknown directory |
--no-index |
check state only, do not index |
--force |
bypass the freshness cache |
--json |
machine-readable outcome: status ∈ actual·reindexed·created·not_a_project·error, config, rev_id, files, reason, notes[], seconds
|
not_a_project is a deliberate guard (no .git/manifests — a home directory or drive root never becomes a corpus), not an environment error.
Register the development effort in the machine registry (catalog/catalog.json).
Full indexing → new rev-NNNN. --no-vectors: skip the embedding layer (no model download; lexical search works). --limit-files: pilot revisions (P7). With --json prints {rev_id, ok, files, seconds, …}. Records the run in the registry.
New snapshot + archives the drift ledger into drift/archive/<from>_to_<to>.md (three mandatory sections: corpus changes · re-verified knowledge · changed slice borders). History rows are never deleted.
Compare corpus_hash against the revision; reindex if changed (unless --no-reindex).
Register differences without touching the index. --scan = full sha256+symbol comparison; --detected-by ∈ hook:session-start · compare (default) · git-diff · db-schema-diff · manual.
Revision, coverage, capability (+reason), stage timings, ledger size, compute state.
Delete the current revision's data (history is preserved). With index afterwards — the reproducibility check (NFR-6).
Environment report on 11 components: python, tree_sitter, php_grammar, sqlite_vec, fastembed, tiktoken, fts5, vec0_loadable, embedding_model (required) + joern, java (optional). --json (global, before the subcommand) gives {checks:[{check, ok, detail}], versions, all_ok}.
Always exits 0. It is a report, not a gate — a «green selftest» proves nothing by itself; read the checks.
The registry: per effort — revision, checksum, hash_matches, counts, run history. (No --json yet — roadmap R-CLI-2; the installer parses text as a fallback.)
Call telemetry and effect estimate. --agent-kind ∈ autoclaw · external · internal; --task filters by the RAGRAF_TASK label (statistics for ONE task across processes); --reset clears the journal for a clean before/after measurement.
ragraf -p <cfg> [--json] query <op> [text] [flags]
<op> ∈ search · symbol · references · callers · callees · impact · slice · code · repo_map · schema · table_usage · routes · index_status · drift_report · drift_ack · live_read · calibrate · write_check · usage · freshness · catalog · policy_trace · class_usage
Shared flags (validated per operation — a wrong --mode for the op is a usage error, not a silent substitution)
| Flag | Ops | Meaning |
|---|---|---|
text (positional) |
search, write_check, policy_trace, … | primary argument (query / table / policy fn) |
--name / --fqn / --target
|
symbol, code, callers, callees, impact | symbol addressing |
--path |
symbol, live_read, impact | file filter / target file |
--table |
schema, table_usage, write_check, impact | table target |
--depth N (1) |
callers, callees, impact | graph depth 1..3 |
--mode |
impact: full·hard · table_usage: all·read·write · class_usage: all·missing·unused
|
per-op mode sets |
--hard |
impact, callers | proven links only |
--direction back·forward |
slice | slice direction |
--style compact·signatures |
code | body style |
--detail normal·deep |
repo_map | map detail |
--budget N (2000) |
repo_map | character budget |
--limit N (50) |
most list ops | result cap |
--since N |
drift_report | ledger entries after id |
--entry-ids "id1,id2" |
code | node_id/chunk_id from search hits |
--start / --end |
live_read | line window |
--kind |
calibrate | threshold·confidence·embedding |
--note |
drift_ack, drift | acknowledgment/note text |
--with-text, --text-width N (160) |
search | snippet from the index with each hit |
--source auto·index·disk |
code | text source (default: index) |
--include-containers |
code | enclosing-class headers |
--columns "A,B,C", --operation insert·update·delete
|
write_check | the write plan to check |
--action |
policy_trace | trace one action's decision |
--force |
freshness | bypass the 15-s cache |
--scope |
repo_map | map scope |
# navigation
ragraf -p cfg query symbol --name CorpusScanner
ragraf -p cfg query callers --fqn "App\Core\Config::get" --depth 2 --hard
ragraf -p cfg query search "reindex threshold" --with-text --limit 10
# before an edit
ragraf -p cfg query impact --target "DocJournal::submit" --mode hard --depth 3
ragraf -p cfg query write_check DocPayments --columns "No,Status,InitiatorID" --operation insert
# permissions & presentation
ragraf -p cfg query policy_trace z_agr_can_act --action mark_paid
ragraf -p cfg query class_usage z-auth-card --mode missing
# freshness & meta
ragraf -p cfg query freshness --force
ragraf --json -p cfg query index_status| Entry | When | Notes |
|---|---|---|
ragraf |
after pip install -e .
|
console script → ragraf.cli:main
|
python tools/ragraf.py … |
without install, or in scripts | adds src/ to sys.path; removes tools/ from sys.path so the file name never shadows the installed package (a real past defect, fixed & re-verified by the installer) |
scripts/ragraf.ps1 … |
pwsh sessions | resolves the interpreter: -Python → ~/.ragraf/venv → .venv → PATH; enforces ≥3.13; sets PYTHONPATH (platform-correct separator) and PYTHONIOENCODING=utf-8, restores both on exit |
python tools/ragraf-mcp.py … |
MCP server (stdio) | see MCP Integration |
python tools/ragraf-admin.py … |
admin panel | see Admin Panel |
Environment variables: RAGRAF_MODEL_CACHE (model cache dir) · RAGRAF_MODEL_CACHE_FORCE (re-check cache) · RAGRAF_DEBUG=1 (re-raise exceptions instead of exit codes) · RAGRAF_TASK (usage label) · RAGRAF_JOERN_HOME / RAGRAF_JAVA_HOME / RAGRAF_JOERN_HEAP_GB / RAGRAF_PHP_BIN* (CPG layer; *roadmap R-CORE-2).
Next: MCP Integration →