Справочник
Команды CLI
Команды Holkas для скриптов и CI/CD: найти нужный вызов, проверить параметры, понять результат и продолжить операцию.
На этой странице
С чего начать
CLI обращается к серверу Holkas Web по REST API. Базы, Git и S3 доступны серверу; локальный клиент передаёт запросы и файлы, ждёт результат и печатает ответ. Путь в --input, --objects или --out относится к компьютеру, где запущен CLI.
Установка, токен и первый перенос разобраны в Установка → CLI. Здесь предполагается, что HOLKAS_SERVER и HOLKAS_API_KEY уже заданы. В PowerShell из каталога клиента используйте .\holkas.exe, если клиент не добавлен в PATH.
Имена подключений, объектов, манифестов и номера операций в примерах условные. Замените их своими. Синтаксис в блоках с <…> — шаблон вызова; квадратные скобки означают необязательный параметр и не вводятся в консоль.
Сервер, подключения, каталог
status — сервер и текущий вход
holkas status [--json]
Обязательно: дополнительных аргументов нет.
Результат: адрес, версия и режим сервера, сведения о входе. Запрос не проверяет доступность баз данных.
Пример: holkas status --json.
Учесть: код 0 означает, что сведения получены. Вход при этом может быть не выполнен: в JSON проверяйте authenticated.
connections list — доступные подключения
holkas connections list [--json]
Обязательно: дополнительных аргументов нет. Короткий вызов holkas connections тоже выводит список.
Результат: доступные владельцу токена подключения с именем, транспортом и адресом.
Пример: holkas connections list.
Учесть: наличие подключения в списке не проверяет связь с ним. Для этого есть следующая команда.
connections test — проверить связь
holkas connections test <подключение> [--json]
Обязательно: имя или id подключения.
Результат: OK: и код 0, если проверка прошла; FAILED: и код 1, если подключение не отвечает. В JSON результат находится в ok и message.
Пример: holkas connections test "Разработка".
Учесть: сначала ищется точное имя. Число считается id, только если такого имени нет. Имена с пробелами берите в кавычки. Это правило действует и для других команд с подключениями, описателями и манифестами; при нескольких манифестах одного имени указывайте id.
catalog refresh — обновить каталог объектов
holkas catalog refresh <подключение> [--timeout <сек>] [--json]
Обязательно: имя или id подключения.
Результат: запускает обход каталога и ждёт его окончания; при успехе выводит число объектов и возвращает 0. Неуспешный итог — 1, предел ожидания — 5.
Пример: holkas catalog refresh "Разработка" --timeout 600.
Учесть: каталог нужен для сверки состава через expand --source. По тайм-ауту обход не отменяется. Это задание каталога, а не операция переноса: клиент предлагает снова вызвать catalog refresh, а не operation.
Состав сборки
expand — получить список объектов
holkas expand --describer <описатель> --root ТИП:ИМЯ [--root ТИП:ИМЯ] [--source <подключение>] [--out <файл>] [--strict]
holkas expand --manifest <манифест> [--source <подключение>] [--out <файл>] [--strict]
Обязательно: один из двух способов — описатель с хотя бы одним --root либо существующий манифест. --describer и --manifest вместе не допускаются. Повторением --root задают несколько корней.
Результат: размеченный список состава. С --out годные строки записываются в JSON-файл для параметра --objects.
Пример:
holkas expand --manifest "Релиз 1.4" --source "Разработка" --out objects.json --strict
Учесть: без --source состав не сверяется с базой. Указанный источник тоже не гарантирует сверку, если его каталог ещё не обойдён: сначала выполните catalog refresh.
| Пометка строки | Значение | Попадает в --out |
|---|---|---|
ok | Объект найден в каталоге источника | Да |
unchecked | Строка не сверена с источником | Да |
not_in_source | В каталоге источника объект не найден | Нет |
unsupported_type | Тип не поддерживается | Нет |
no_definition | У набора данных нет годного описания; причина указана рядом | Нет |
--strict возвращает 1, если есть отвергнутые строки. Файл годных строк всё равно записывается. Без --strict наличие отвергнутых строк не меняет успешный код 0. Пометка unchecked сама по себе не считается отказом даже с --strict.
Файл содержит массив объектов. У DAT поле definition передаёт описание набора данных. Пример без набора данных:
[
{ "type": "CLS", "name": "DemoRequest" },
{ "type": "JFP", "name": "parus.demo_check" }
]
manifest list — найти манифест
holkas manifest list [--json]
Обязательно: дополнительных аргументов нет.
Результат: id, имя и число объектов доступных манифестов.
Пример: holkas manifest list.
Учесть: манифест хранит состав, а не содержимое объектов. Подробнее — работа с манифестом.
manifest export — сохранить манифест в файл
holkas manifest export <манифест> --out <файл> [--json]
Обязательно: имя или id манифеста и путь файла в --out.
Результат: файл манифеста на компьютере клиента. В JSON — manifestId, path, sizeBytes.
Пример: holkas manifest export "Релиз 1.4" --out manifest.json.
Учесть: этот файл предназначен для manifest import. Это не массив --objects и не ZIP-пакет объектов. Описания наборов данных сохраняются в параметрах строк манифеста.
manifest import — загрузить манифест
holkas manifest import <файл> [--json]
Обязательно: существующий файл манифеста, полученный при экспорте.
Результат: манифест создаётся на сервере; клиент выводит его имя и id.
Пример: holkas manifest import manifest.json.
Учесть: сервер проверяет хеш содержимого до записи. Импорт манифеста не выполняет перенос его объектов.
Перенос
| Нужный результат | Команда |
|---|---|
| Построить план и остановиться | plan или migrate --dry-run |
| Построить план и перейти к применению | migrate |
| Применить конкретный готовый план | apply <операция> |
| Выполнить перенос без промежуточного плана | migrate --direct |
Параметры сравнения и применения
Планы CLI наследуют «Соответствие ролей», «Замену владельцев», сохранение лишних прав и режим одной транзакции из параметров подключения-приёмника и настроек запуска сервера. Отдельных флагов CLI для roleMap, ownerMap и singleTransaction сейчас нет. Для переопределения на один план используйте Web, REST или MCP.
Если источник — ZIP с требованием одной транзакции, оно действует и через CLI: пакет устанавливается в PostgreSQL целиком, режим нельзя выключить настройкой приёмника. Правила обязательной установки.
plan — построить план
holkas plan --from <источник> --to <приёмник> [объекты] [параметры переноса]
Обязательно: --from и --to; состав объектов либо входной пакет задаются по правилам ниже.
Результат: создаёт операцию, ждёт готовности плана и выводит сводку — команды по действиям и типам, окно объектов, сошедшиеся объекты и предупреждения. При готовом плане возвращает 0. Обычные команды ещё не применяются. Скрипт автора с atPlan: true уже выполняется в приёмнике с откатом транзакции; границы этого отката нужно учитывать до запуска.
Пример:
holkas plan --from "Разработка" --to "Тест" --object CLS:DemoRequest --reason "TASK-1234 · Проверка класса"
Учесть: полный список команд, выбор для запуска и подробные различия смотрите в веб-интерфейсе. Чтобы применить именно этот план, сохраните id операции и используйте apply. Новый вызов plan создаёт другую операцию. --direct и --confirm для plan недопустимы.
migrate — построить и применить
holkas migrate --from <источник> --to <приёмник> [объекты] [параметры переноса] [--dry-run | --direct]
Обязательно: --from и --to; состав либо пакет, как у plan.
Результат: в обычном режиме строит план и переходит к применению. Успешное завершение — 0; пустой план также даёт 0, без запуска применения. При необходимости подтверждения возвращает заявку и код 4.
Пример:
holkas migrate --from "Разработка" --to "Тест" --objects objects.json --reason "TASK-1234 · Перенос класса"
Учесть: --dry-run останавливается на плане. --direct выполняет перенос за один проход без промежуточного плана; так выгружают в файл пакета, SQL-скрипт или S3. С --dry-run он несовместим. Прямое применение в базу также требует подтверждения.
Что находится в SQL-файле и как проверить его самостоятельное выполнение — в примере SQL-выгрузки.
После заявки обычного migrate продолжайте через apply <операция> --confirm <заявка>. Только для migrate --direct повторяется тот же вызов migrate с --confirm.
apply — применить готовый план
holkas apply <операция> [--reason <основание>] [--confirm <заявка>] [--timeout <сек>] [--out <каталог>]
Обязательно: id уже созданной операции с готовым планом.
Результат: запрашивает применение, ждёт итог и выводит состояние операции. Успешный перенос — 0, ошибка или отмена операции — 1, необходимость подтверждения — 4.
Пример: holkas apply op-demo --reason "TASK-1234 · Перенос класса".
Учесть: маршрут и состав берутся из операции; --from, --to и --objects здесь не задаются. Пустой план сервер отклоняет: это отличается от обычного migrate, который распознаёт его до вызова применения.
Объекты и параметры переноса
Эти параметры относятся к plan и migrate, если отдельно не указано другое.
| Параметр | Что передать |
|---|---|
--from, --to | Имена или id подключений источника и приёмника |
--object ТИП:ИМЯ | Один объект, например CLS:DemoRequest. Можно повторять |
--objects <файл> | JSON-массив с type и name, в том числе из expand --out. Складывается со строками --object |
--input <файл> | ZIP для источника «Файл пакета». Для такого источника перечень объектов не нужен |
--source-ref <ref> | Ветка, тег или коммит Git-источника; без параметра — ветка подключения по умолчанию |
--target-ref <ветка> | Ветка Git-приёмника |
--source-company <организация> | Название или RN организации Паруса в источнике |
--target-company <организация> | Организация приёмника. Нужна, если организаций несколько и она не задана в подключении |
--output-name <имя> | Имя файла у файлового приёмника. Расширение .zip или .sql добавляется, если его нет |
--out <каталог> | Скачать доступные выходные файлы после ожидания применения; также у apply. Наличие файла не заменяет проверку итога операции |
--reason <основание> | Необязательное пояснение до 255 символов; также у apply. Если при apply опустить, сохраняется основание плана |
--timeout <сек> | Предел одного этапа ожидания, по умолчанию 3600; также у apply и catalog refresh. Положительное целое число |
--confirm <заявка> | Номер заявки: только у apply или migrate --direct |
Для DAT в строке файла --objects обязательно описание definition: JSON-объект или строка с JSON формата holkas-dataset/1. Одного --object DAT:Имя недостаточно для передачи описания. Синтаксис описания и примеры — формат набора данных; поведение переноса — справочник DAT.
Подтверждение
Применение в базу данных требует решения человека. CLI не ждёт этого решения в открытом процессе: возвращает код 4, номер заявки и подсказку продолжения в stderr.
Одна операция, несколько запусков CLI
- Команда на вашем компьютере
holkas plan …Ждёт готовности плана → код 0
Состояние на сервереPlanBuilding → PlanReadyСоздана операция op-demo. В базе-приёмнике ещё ничего не изменено.
- Команда на вашем компьютере
holkas apply op-demoВозвращает заявку → код 4
Состояние на сервереPlanReadyПлан готов. Применение ещё не началось: нужно решение человека.
- Команда на вашем компьютере
holkas apply op-demo --confirm 17После одобрения: запускает применение и ждёт
Состояние на сервереApplying → CompletedПрименяется тот же план. Если перенос завершён успешно, CLI возвращает 0.
Заявка действует 30 минут, привязана к пользователю, операции и параметрам подтверждаемого действия. Повторите то же основание --reason, если задавали его при запросе. Просроченная заявка не разрешает выполнение: запросите применение заново и получите новую.
Для обычного переноса человек после просмотра плана запускает:
holkas apply op-demo --reason "TASK-1234 · Перенос класса" --confirm 17
Для migrate --direct повторяется тот же исходный вызов, с теми же параметрами и добавленным --confirm 17. В конвейере CI это отдельный шаг ручного одобрения; автоматически повторять любую полученную заявку с --confirm не следует — так решение человека подменяется скриптом.
Выгрузка в Git, S3 и файлы по умолчанию выполняется без подтверждения. Личные настройки автономии могут потребовать его и для этих операций.
proposals — ожидающие заявки
holkas proposals [list] [--json]
Обязательно: дополнительных аргументов нет.
Результат: список ожидающих заявок с id, действием, сроком и описанием. Пустой список — успешный результат 0.
Пример: holkas proposals.
Учесть: просмотр списка ничего не подтверждает. Продолжение выполняется исходной командой с --confirm, а не отдельной командой одобрения.
proposals reject — отклонить заявку
holkas proposals reject <заявка> [--json]
Обязательно: номер заявки.
Результат: заявка отклонена; при успешном запросе — 0.
Пример: holkas proposals reject 17.
Учесть: это отказ от ожидающего действия. Команда не отменяет уже начавшееся применение и не откатывает изменения.
Операции и файлы
operation — узнать текущее состояние
holkas operation <операция> [--json]
Обязательно: id операции.
Результат: состояние, сводка плана, ошибка и сведения о файлах. Выполняется один запрос сведений об операции и запрос сводки; ожидания окончания нет.
Пример: holkas operation op-demo --json.
Учесть: код 0 возможен и при Failed. Он означает, что запрос сведений выполнен. В JSON смотрите operation.status, а при неудаче — operation.error.
| Состояние | Что делать |
|---|---|
PlanBuilding | План ещё строится; запросить состояние позже |
PlanReady | План готов. Посмотреть его, затем при необходимости вызвать apply |
Applying | Применение идёт; запросить состояние позже |
Completed | Выполнение завершено; при необходимости скачать файлы |
Failed | Прочитать ошибку и журнал; часть команд могла уже выполниться |
Cancelled | Операция отменена до применения. Идущее применение отменить нельзя. В операциях прежних версий этот статус не доказывает отката изменений |
log — прочитать журнал
holkas log <операция> [--level info|debug|error] [--tail N] [--json]
Обязательно: id операции.
Результат: последние строки журнала; по умолчанию уровень info и до 1000 строк. debug включает подробные сообщения, error оставляет ошибки. N — положительное целое число.
Пример: holkas log op-demo --level error --tail 50.
Учесть: это разовое чтение, без непрерывного слежения. Пока операция идёт, строки появляются с задержкой в пару секунд; если их ещё нет, команда так и скажет. Если операция завершена, а журнал не сохранён, сервер вернёт отказ. JSON содержит status, inProgress, note, total, shown, lines.
download — скачать файлы операции
holkas download <операция> [--out <каталог>] [--all] [--json]
Обязательно: id операции.
Результат: скачивает созданные файлы, по умолчанию в текущий каталог. --all добавляет входные файлы операции. JSON содержит массив записей с artifactId, role, path, sizeBytes.
Пример: holkas download op-demo --out dist.
Учесть: окончания операции не ждёт. В обычном режиме отсутствие файлов даёт код 1; с --json — пустой массив [] и код 0. Это текущее различие режимов: в скрипте проверяйте и длину массива. Файл с тем же именем в каталоге назначения перезаписывается.
Общие параметры
| Параметр | Значение и приоритет |
|---|---|
--server <адрес> | Имеет приоритет над HOLKAS_SERVER; без обоих — http://localhost:5000 |
--api-key <токен> | Имеет приоритет над HOLKAS_API_KEY |
--json | Структурированный результат в stdout, сообщения о ходе работы и отказы — в stderr |
--help, -h | Общая справка клиента: holkas --help. Сервер для неё не нужен |
Параметры со значениями пишутся через пробел: --timeout 60, а не --timeout=60. Для повторяемых --object и --root учитываются все значения; для обычного параметра при повторе используется последнее.
--timeout ограничивает отдельное ожидание: у migrate построение плана и применение получают каждый свой предел. Это не общий бюджет всей команды и не тайм-аут отдельного HTTP-запроса. CLI опрашивает состояние примерно раз в две секунды. При тайм-ауте HTTP-запроса возвращается код 2, а не 5.
JSON и потоки вывода
С --json клиент пишет итоговый JSON в stdout, а прогресс — в stderr. Успешный результат — один JSON-документ; при ошибке разбора аргументов или связи stdout может быть пустым. Серверный отказ, включая заявку на подтверждение, выводится в stdout как JSON ошибки, а пояснение — в stderr.
| Вызов | Где искать нужное |
|---|---|
status --json | authenticated — выполнен ли вход |
plan --json, migrate --dry-run --json | id, status, summary — сводка плана |
apply --json, migrate --direct --json | operation.id, operation.status, saved — операция и скачанные файлы |
Обычный migrate --json | При пустом плане или остановке на построении — сводка плана; после применения — operation и saved; при отказе — JSON ошибки |
operation --json | operation.status; saved пуст, поскольку команда ничего не скачивает |
download --json | Массив файлов, в том числе пустой |
Например, в Bash результат и сообщения можно сохранить раздельно:
holkas operation op-demo --json > operation.json 2> operation.log
Сначала проверьте код завершения вызова, затем разбирайте соответствующую форму JSON. Сведения о доступном обновлении CLI также идут только в stderr и не меняют результат команды. Подробнее — проверка новых версий.
Коды завершения
| Код | Значение | Следующий шаг |
|---|---|---|
0 | Команда выполнена успешно в своём смысле | Для operation проверить состояние операции; для status — вход; для download --json — массив файлов |
1 | Отрицательный итог: ошибка или отмена операции, проверка не прошла, --strict отверг строки, обычный download не нашёл файлов | Прочитать результат и устранить причину |
2 | Отказ сервера, нет связи или HTTP-запрос не завершился вовремя | Прочитать код и сообщение ошибки. Если запуск уже мог начаться — проверить существующую операцию |
3 | Обнаружена ошибка аргументов командной строки | Исправить вызов по сообщению клиента |
4 | Требуется подтверждение | Человек рассматривает действие и продолжает с --confirm либо отклоняет заявку |
5 | Истёк --timeout ожидания | Проверить состояние уже созданной операции; для каталога следовать подсказке catalog refresh |
130 | CLI прерван Ctrl+C | Уже начатая серверная работа продолжается; проверить её состояние |
После тайм-аута не запускайте автоматически новый migrate: он создаёт новую операцию. Найдите id старой в выводе клиента или истории сервера и проверьте её через operation.
Типичный конвейер сборки
Пример для Bash: манифест «Релиз 1.4» уже существует, подключения настроены. set -e останавливает этот пример при ненулевом коде любого шага — включая отказ expand --strict; частичный список не попадёт в выгрузку.
set -e
holkas catalog refresh "Разработка"
holkas expand --manifest "Релиз 1.4" --source "Разработка" --out objects.json --strict
holkas migrate --direct --from "Разработка" --to "Файл пакета" --objects objects.json --reason "TASK-1234 · Выпуск сборки" --output-name release-1.4 --out dist
При успешном завершении пакет находится в dist/release-1.4.zip. Его можно сохранить как артефакт CI. Если вместо манифеста используется описатель сборки, замените второй шаг на expand --describer <описатель> --root <ТИП:ИМЯ> ….
Для переноса в базу разделите конвейер на построение плана и применение после ручного одобрения. Пример полного первого запуска — в руководстве по CLI; поведение самого плана — в «Как строится план».
Что учесть при разборе JSON
Сводка описывает объект верхнего уровня; поле parts содержит состав изменения (kind, name, created, updated, deleted). Нулевые счётчики могут отсутствовать. Не определяйте тип объекта по первой команде его части. Описание сводки.
Даты имеют указание UTC. JSON журнала содержит также status, inProgress и note: пустой журнал идущей операции ещё может наполняться. Скачивание такого журнала без записей отвечает 409 operation_in_progress. После завершения проверьте итог повторным чтением.