CLI: команды, флаги, коды выхода

Полный справочник командной строки ragraf: установка, ensure, query, reindex, selftest, порядок глобальных флагов и коды выхода.

Точка входа #

Shell

ragraf -p config/mycorpus.yaml <команда> [аргументы]
# или без установки пакета:
python tools/ragraf.py -p config/mycorpus.yaml <команда>

Обёртка tools/ragraf.py сама добавляет src/ в sys.path — работает из клона репозитория без pip install.

Порядок флагов — частая ошибка: глобальные --project/-p и --json идут до подкоманды:

Shell

ragraf -p cfg.yaml --json query search "порог"     # ✓
ragraf query search "порог" -p cfg.yaml            # ✗ аргумент не распознан

Исключение — ensure: у неё собственный --json, который ставится после (это зафиксированный контракт, а не недосмотр):

Shell

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

Команды верхнего уровня #

Команда	Назначение
`init <dir>`	создать конфигурацию корпуса для каталога (интерактивные значения заменяются разумными дефолтами)
`ensure <dir>`	идемпотентно: найти/создать корпус, проверить свежесть, при расхождении переиндексировать
`index` / `reindex`	полная пересборка ревизии; журнал расхождений архивируется в отчёт
`status`	сводка: ревизия, capability, размеры, дрейф
`selftest`	отчёт по компонентам окружения (9 обязательных + joern/java опционально). Всегда exit 0 — это отчёт, не гейт; читать тело отчёта
`query <операция>`	любая из операций фасада: `search`, `symbol`, `callers`, `impact`, `slice`, `schema`, `write_check`, `routes`, `policy_trace`, `drift_report`, `usage_stats`, …
`serve-mcp`	запустить MCP-сервер (обычно запускается агентом, не человеком)
`admin`	запустить локальную админ-панель (127.0.0.1:8777)

Примеры из реальной практики #

Shell

# найти символ и его входящие вызовы
ragraf -p cfg.yaml query symbol --name corpus_hash
ragraf -p cfg.yaml query callers --name z_agr_audit_log --mode all

# гибрид-поиск с немедленной выдачей текста фрагментов (без второго вызова)
ragraf -p cfg.yaml query search "порог переиндексации" --with-text --top 8

# проверка плана записи ДО выполнения SQL
ragraf -p cfg.yaml query write_check --table z_agr_payments --columns "amount,AuthorUserID"
# → колонка AuthorUserID не найдена; ближайшие: InitiatorID, UpdatedBy

# отчёт «что изменилось в знаниях» после правок
ragraf -p cfg.yaml query drift_report

Выходные форматы #

--json — машиночитаемый конверт (тот же, что у MCP; см. операции).
без флага — компактный человекочитаемый вывод; таблицы не рисуются, факты — построчно с path:line.

JSON пригоден для пайпов: ragraf -p cfg --json query symbol --name X | jq '.result[] | .path'. Установщик и selftest-обвязки парсят именно --json (в рефакторинге установщика добавлены таймауты и защита от deadlock пайпов — см. INSTALLER-REFACTOR-NOTES в репозитории).

Коды выхода #

Код	Значение	Типичная причина
0	успех (для `selftest` — «отчёт сформирован», даже если компоненты отсутствуют)	—
1	ошибка аргументов/корпуса	флаг после подкоманды; нет конфига; корпус не найден
2	внутренняя ошибка	повреждённое хранилище; баг (сообщите на GitHub Issues с трассировкой)
3	операция невозможна в этом состоянии	`slice` при `capability=degraded`; отказ с явной причиной

Код 3 — не «ничего не найдено». «Не найдено» — это успешный ответ с пустым result и объявленными limits. Различие принципиально: отсутствие факта и невозможность операции — разные события (анти-требование №4).

Переменные окружения #

Переменная	Влияние
`RAGRAF_MODEL_CACHE`	каталог кэша модели эмбеддингов (по умолчанию `~/.ragraf/models`)
`RAGRAF_JOERN_HEAP_GB`	heap для Joern-сервера (большие корпуса)
`RAGRAF_DEBUG`	подробные трассировки в stderr
`RAGRAF_ADMIN_TOKEN`	токен мутаций админ-панели (иначе печатается в консоль при старте)

Windows-заметки #

PowerShell 7.6+ проверен; Windows PowerShell 5.1 не проверялся.
Пути с пробелами — в кавычках; glob-паттерны в конфиге — прямым слешем / (обратные работают, но / каноничен).
Известный зазор установщика: case-чувствительность glob на Windows описана в реестре дефектов (D-регистр, E-01) — обход: нормализация путей в конфиге.

Смежное: установка и первый запуск → · конфигурация корпуса →