Руководство описывает работу с CLI в подготовленной локальной копии исходников CodeGraph. Нужны Python 3.11 или новее, установленные зависимости проекта и Git для сравнения файлов. Установку сервера описывает отдельное руководство.
В примерах python обозначает интерпретатор окружения с зависимостями CodeGraph.
Если оно находится в .venv, используйте .\.venv\Scripts\python.exe
или активируйте окружение перед запуском команд.
Для выполнения CLI в локальном config.yaml требуется
security.local_cli_enabled: true. Меняйте только этот параметр, сохраняя
остальную конфигурацию. Включайте его только в локальной среде разработки.
Сообщение CodeGraph CLI is disabled. означает, что запуск отклонён;
команда возвращает код 2. После успешного запуска проверьте данные результата.
В корне репозитория запустите:
python -m src.cli --help
Пакет публикует консольные команды codegraph-acp и codegraph-lsp. Основной CLI
из локальной копии исходников запускается через python -m src.cli.
Если ваше развёртывание предоставляет отдельную обёртку, проверьте её собственную
справку --help.
Форма команды
Форма вызова из локальной копии исходников:
python -m src.cli <command> [subcommand] [options]
Проверяйте help на нужном уровне:
python -m src.cli import --help
python -m src.cli projects --help
python -m src.cli audit --help
python -m src.cli review --help
python -m src.cli doctor --help
Справка установленной версии перечисляет поддерживаемые флаги и значения. Устаревшие псевдонимы и параметры, которых нет в справке, не поддерживаются.
Безопасные первые команды
Начните с проверки конфигурации из корня репозитория:
python -m src.cli doctor config --json
В JSON-отчёте поле scope равно config. Проверьте результаты config.config_yaml и config.projects_yaml: они показывают корректность файлов конфигурации и реестра проектов. При overall_status=pass команда возвращает код 0; предупреждения дают код 1, ошибки — код 2.
Затем соберите общую диагностику и сведения о проектах и языках:
python -m src.cli doctor --json
python -m src.cli projects list
python -m src.cli languages
Для операции с проектом укажите проект или проверьте, какой проект выбрала команда. Для интерфейсов агентов используйте идентификатор проекта: сервер определит связанное хранилище из контекста.
Типовые задачи
| Задача | Начальная команда | Что сохранить |
|---|---|---|
| Импорт репозитория | python -m src.cli import --help |
Выбранный источник, идентификатор проекта и статус задания |
| Проверка проекта | python -m src.cli projects info <name> |
Организация, группа, проект и актуальность данных |
| Аудит проекта | python -m src.cli audit --help |
Параметры, ревизия и файл с результатами |
| Ревью изменений | python -m src.cli review --help |
Исходная и целевая ревизии, расположение найденных проблем |
| Диагностика | python -m src.cli doctor --json |
Диагностический JSON до исправления |
| Формирование SBOM | python -m src.cli sbom --help |
Ревизия проекта, формат и контрольная сумма результата |
Полный цикл импорта описан в руководстве по импорту, режимы аудита и проверяемые результаты — в аудите проекта на основе CPG, а восстановление — в диагностике.
Поиск функции и сравнение файлов
Команда edit find ищет элементы исходного кода. Чтобы проверить её на небольшом
примере, сохраните файл example.py в рабочем каталоге:
def greeting(name):
return "Hello, " + name
Из корня репозитория CodeGraph запустите команду в PowerShell. Если файл находится
в другом каталоге, замените example.py его путём в кавычках:
python -m src.cli edit find greeting --file example.py --exact
В результате должна появиться функция greeting из файла example.py.
Если имя не найдено, команда выводит No targets found matching и возвращает
код 0. Поэтому проверяйте найденные элементы, а не только код завершения.
Команда не изменяет исходный файл.
В текущей реализации edit preview зарегистрирована, но вызов с найденной
целью завершается ошибкой AttributeError: 'DiffGenerator' object has no
attribute 'generate_diff'. Не используйте эту команду как рабочий предпросмотр.
Чтобы сравнить два файла, сохраните предложенную версию в replacement.py:
def greeting(name):
return f"Hello, {name}!"
При установленном Git выполните:
git diff --no-index -- example.py replacement.py
Вывод должен показать удаление строки return "Hello, " + name и добавление
строки return f"Hello, {name}!". Git возвращает код 1, когда файлы различаются,
и код 0, когда они одинаковы. Эта проверка сравнивает файлы целиком и не изменяет
их. В предложенной версии приветствие заканчивается знаком !.
Команды apply, undo и history пока не реализованы и возвращают код 1
с сообщением not yet implemented. Применяйте согласованную правку в редакторе,
затем запускайте тесты и проверяйте diff проекта.
Служебные учётные записи
Администратор может изучить операции со служебными учётными записями через справку:
python -m src.cli auth service-account --help
python -m src.cli auth service-account create --help
python -m src.cli auth service-account list --help
python -m src.cli auth service-account inspect --help
python -m src.cli auth service-account rotate --help
python -m src.cli auth service-account revoke --help
python -m src.cli auth service-account deactivate --help
Секрет, возвращённый create или rotate, показывается однократно. Назначайте
только необходимые действия и проекты. Сохраняйте идентификатор учётных данных,
а не секрет. После отзыва доступа проверьте результат revoke или deactivate.
Авторизация и взаимная TLS-аутентификация (mTLS) описаны в
руководстве по RBAC.
Снимки прослеживаемости
Раздел dashboard snapshot управляет снимками прослеживаемости:
python -m src.cli dashboard snapshot --help
python -m src.cli dashboard snapshot show --help
python -m src.cli dashboard snapshot policy --help
Команда show возвращает неизменяемые метаданные, а policy — правила управления
снимками установленной версии. Справка также описывает просмотр списка, сравнение
и экспорт. Операции удаления нет: свидетельства выпуска и портфеля проектов должны
сохранять идентификатор снимка. Подробнее — в
справочнике снимков.
Автоматизация
- Фиксируйте релиз CodeGraph и ревизию репозитория.
- Проверяйте совместимость через
--help: сохранённый список команд может устареть. - Явно задавайте путь для результатов, которые нужно сохранить.
- Проверяйте значение кода завершения для конкретной команды. Например,
git diffвозвращает 1 при различии файлов. Код завершения сам по себе не подтверждает приёмку продукта. - Храните токены и пароли в разрешённом хранилище секретов, а не в аргументах или логах.
Справочные материалы
Если команда завершается ошибкой, используйте руководство по диагностике.
См. также: Краткий справочник · OpenCode quick start