Holkas
Написать в поддержку Поддержка

Справочник

Команды 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

  1. Команда на вашем компьютереholkas plan …

    Ждёт готовности плана → код 0

    Состояние на сервереPlanBuilding → PlanReady

    Создана операция op-demo. В базе-приёмнике ещё ничего не изменено.

  2. Команда на вашем компьютереholkas apply op-demo

    Возвращает заявку → код 4

    Состояние на сервереPlanReady

    План готов. Применение ещё не началось: нужно решение человека.

  3. Команда на вашем компьютереholkas apply op-demo --confirm 17

    После одобрения: запускает применение и ждёт

    Состояние на сервереApplying → Completed

    Применяется тот же план. Если перенос завершён успешно, CLI возвращает 0.

Условный пример переноса в базу: op-demo — обозначение операции, 17 — номер заявки. Подставляйте значения своего запуска.

Заявка действует 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 --jsonauthenticated — выполнен ли вход
plan --json, migrate --dry-run --jsonid, status, summary — сводка плана
apply --json, migrate --direct --jsonoperation.id, operation.status, saved — операция и скачанные файлы
Обычный migrate --jsonПри пустом плане или остановке на построении — сводка плана; после применения — operation и saved; при отказе — JSON ошибки
operation --jsonoperation.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
130CLI прерван 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. После завершения проверьте итог повторным чтением.