Установка
CLI
От первой команды до готового пакета: подключите консольный клиент, постройте план, откройте diff в браузере и выгрузите результат в ZIP. Те же подключения, права и история, что в Holkas Web.
На этой странице
Скачайте клиент для своей системы
На странице релизов скачайте архив CLI и SHA256SUMS из того же выпуска. Для Linux — holkas-cli-linux-x64-<версия>.tar.gz, для Windows — holkas-cli-win-x64-<версия>.zip. Ниже Bash для уже скачанных файлов; вариант PowerShell приведён отдельно.
archive=holkas-cli-linux-x64-0.1.36.tar.gz
if awk -v file="$archive" '$2 == file { print }' SHA256SUMS |
sha256sum --check --strict -; then
tar -xzf "$archive" &&
export PATH="$PWD/holkas-cli-linux-x64:$PATH" &&
holkas --help
fi Команды выполняются в папке со скачанными файлами. В имени архива стоит последний выпуск; если скачали другую версию, замените имя на своё. Добавление в PATH действует в текущем терминале. При несовпадении суммы распаковка не выполняется — скачайте архив заново.
Проверка суммы дала OK, а holkas --help вывел список команд. Сам сервер эта команда не запускает.
Выпустите токен для скрипта
В Holkas откройте «Полномочия → Мой агент». В карточке «Токены доступа» укажите понятное имя, выберите «для скрипта» и нажмите «Создать». Скопируйте токен сразу — целиком он показывается один раз.
CLI получает ваши права. Для регулярного задания используйте отдельную учётную запись с нужными разрешениями. Токен «для агента» предназначен для MCP и не подходит для CLI.
У вас есть адрес нужного экземпляра Holkas и токен для скрипта, выпущенный именно в нём.
Проверьте вход и подключение
В Bash задайте адрес своего Holkas и вставьте токен в скрытый запрос. Для локального Docker из нашей инструкции это http://localhost:8080; на другом компьютере нужен адрес сервера. Для Windows используйте настройку PowerShell.
export HOLKAS_SERVER=http://localhost:8080
read -rsp 'Токен Holkas: ' HOLKAS_API_KEY
printf '\n'
export HOLKAS_API_KEY
holkas status
holkas connections list
holkas connections test "Учебная · приёмка" Подставьте имя своей тестовой базы из списка. Токен вводится отдельно от команды и не попадает в историю оболочки. Переменные действуют в этом терминале и запускаемых из него процессах.
В status показано ваше имя, в списке есть нужное подключение, а проверка связи отвечает OK:. Один код 0 от status ещё не подтверждает вход — прочитайте строку «Вход».
Постройте первый план
Сравним сохранённую версию функции в Git с тестовой базой. В нашем примере база уже содержит более новую версию: задача — увидеть различия со старым коммитом. Команда plan готовит изменения и оставляет их на просмотр; базу не меняет.
holkas plan --from "Учебная · GitHub" --source-ref b5d8a36b6c422f201585f85d26740d4c6cc15c97 --to "Учебная · приёмка" --object JFP:parus.f_hksite_contract_check --reason "Учебный CLI: сравнить сохранённую версию без применения" Вывод учебного запуска — номер операции у вас будет другим
Операция 06d0bd97d40a: PlanReady
Команд: 1 (исключено из запуска 0)
по действиям: Update 1
по типам: JFP 1
Объекты (1):
Update JFP parus.f_hksite_contract_check [1]Если своего Git пока нет, укажите базу-источник в --from и уберите --source-ref. Имена подключений и объекта замените своими. Одна строка команды подходит и для Bash, и для PowerShell после настройки PATH.
В нашем запуске получился PlanReady и одна команда Update. В вашем плане число команд зависит от различий; ноль команд без ошибки означает, что выбранные объекты уже совпадают.
Откройте ту же операцию и прочитайте diff
Скопируйте номер из консоли. В браузере откройте <адрес Holkas>/migrate/<номер операции> либо найдите его в «Истории». Выберите строку функции и нажмите «Diff исходного кода»; режим «Все строки» покажет код с контекстом.
holkas operation PLAN_ID
holkas log PLAN_ID --tail 20 Замените PLAN_ID своим номером. operation показывает состояние и сводку, log — журнал. Краткий вывод консоли не заменяет полный план: команды, предупреждения и код удобнее просмотреть в браузере.
Номер операции в консоли и браузере совпадает. Для этого примера остановитесь на просмотре: возвращать старую версию функции в базу не требуется.
Получите ZIP для передачи
Второй независимый сценарий — выгрузка текущей функции из базы в пакет. Здесь migrate --direct выполняет экспорт в «Файл пакета», а --out скачивает результат на компьютер с CLI. Это не применение предыдущего плана.
holkas migrate --direct --from "Учебная · разработка" --to "Файл пакета" --object JFP:parus.f_hksite_contract_check --reason "Учебный CLI: выгрузка функции в ZIP" --output-name contracts-cli --out dist Путь dist/contracts-cli.zip относится к текущей папке терминала, а не к серверу Holkas. Если файл понадобится ещё раз, выполните holkas download <номер операции> --out dist, пока артефакт хранится на сервере.
Команда завершилась кодом 0, операция имеет статус Completed, в dist появился contracts-cli.zip. Пакет можно передать коллеге или сохранить как артефакт сборки — как работать с пакетом.
Клиент в Windows и PowerShell
Windows CLI 0.1.20 проверен в PowerShell 5.1 на Windows 10 Enterprise LTSC 21H2 x64 вместе с Windows-сервером той же версии: вход по токену, связь с учебным PostgreSQL, план Git → база и выгрузка функции в ZIP. План остался без применения.
Скачайте holkas-cli-win-x64-0.1.36.zip и SHA256SUMS из одного релиза. Откройте PowerShell в папке загрузки; для другой версии замените имя архива. Проверка останавливает этот блок до распаковки при несовпадении суммы:
& {
$archive = 'holkas-cli-win-x64-0.1.36.zip'
$rows = @(Get-Content .\SHA256SUMS | Where-Object {
($_ -split '\s+', 2)[1] -eq $archive
})
if ($rows.Count -ne 1) { throw 'Не найдена единственная контрольная сумма' }
$expected = ($rows[0] -split '\s+', 2)[0]
if ((Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash -ne $expected) {
throw 'Сумма не совпадает. Скачайте архив заново'
}
Expand-Archive -LiteralPath $archive -DestinationPath .\holkas-cli -ErrorAction Stop
$env:PATH = (Join-Path $PWD 'holkas-cli\holkas-cli-win-x64') + ';' + $env:PATH
holkas --help
}
Теперь выпустите токен для скрипта и настройте подключение. В примере адрес локального Holkas Web для Windows; замените его своим. Токен вводится скрыто, не в строке команды:
$env:HOLKAS_SERVER = 'http://localhost:5000'
$secret = Read-Host 'Токен Holkas' -AsSecureString
$env:HOLKAS_API_KEY = [System.Net.NetworkCredential]::new('', $secret).Password
Remove-Variable secret
holkas status
holkas connections list
holkas connections test "Учебная · приёмка"
Дальше выполните команду построения плана выше. Все команды примера записаны в одну строку и подходят для PowerShell. Если не добавляли клиент в PATH, из его папки вызывайте .\holkas.exe вместо holkas.
Из учебного примера в автоматизацию
CLI полезен, когда состав релиза повторяется, пакет нужно собирать по расписанию или план должен стать шагом конвейера. Состав можно брать из манифеста и передавать файлом:
holkas expand --manifest "Договоры" --out objects.json
holkas migrate --direct --from "Разработка" --to "Файл пакета" --objects objects.json --reason "Сборка договоров" --output-name contracts --out dist
Здесь нужны существующий манифест «Договоры» и подключение «Разработка». В конвейере запускайте следующую команду только при успешном завершении предыдущей. Без --source команда expand не сверяет состав с каталогом базы; для строгой проверки используйте полный сценарий сборки.
Адрес задавайте через HOLKAS_SERVER, токен — через секреты конвейера в HOLKAS_API_KEY. Не записывайте токен в репозиторий, командную строку или журнал задания. Флаг --json выводит результат одним JSON-документом в stdout; ход работы идёт в stderr:
holkas operation "$operation_id" --json > operation.json
code=$?
if [ "$code" -ne 0 ]; then
exit "$code"
fi
operation_id здесь — номер ранее созданной операции. В PowerShell после вызова используйте $LASTEXITCODE. Сохраняйте код сразу, прежде чем запускать другую команду.
У operation --json статус лежит в operation.status; у plan --json — в status. Код 0 у команды просмотра operation означает, что сведения получены, даже если сама операция имеет статус Failed. Для контроля результата проверяйте её статус. plan ждёт готовности плана, а migrate — окончания переноса и возвращает код по его результату.
| Код | Что делать в сценарии |
|---|---|
0 | Команда успешна. У просмотра операции отдельно проверьте статус; у плана успех ещё не означает применение. |
1 | Проверить отрицательный результат: ошибка операции, неудачная проверка связи или отвергнутый состав с --strict. |
2 | Разобрать отказ сервера или проблему связи — причина напечатана в stderr. |
3 | Исправить команду и параметры. |
4 | Передать человеку план и заявку на подтверждение; продолжить по напечатанной CLI команде после проверки. |
5 | Истекло время ожидания. Узнать состояние по номеру операции, прежде чем повторять запуск. |
130 | CLI прерван через Ctrl+C. Начатая серверная операция от этого не отменяется. |
Применение в базу требует подтверждения человеком. Не заменяйте plan на migrate механически: migrate запрашивает применение, а --direct используют для поддерживаемых маршрутов экспорта. Порядок ручного подтверждения и продолжения — в справочнике CLI. Истечение --timeout, как и Ctrl+C, останавливает ожидание, а не работу сервера.
Если команда не сработала
| Что видите | Что проверить |
|---|---|
holkas: command not found или команда не распознана | Выполните шаг добавления клиента в PATH в этом терминале либо вызовите файл по пути. В Windows из папки клиента — .\holkas.exe. |
| Сервер недоступен | Проверьте HOLKAS_SERVER, порт и доступ с машины CLI. localhost — именно эта машина. Сервер должен быть запущен отдельно. |
status сообщает «Вход: не выполнен» или сервер отвечает 401 | Токен задан в текущем терминале, не отозван, не истёк и выпущен в этом экземпляре Holkas. |
403 с кодом mcp_token_door | Создайте токен «для скрипта»: переданный токен предназначен для агента. |
| Подключения нет в списке или отказано в доступе | Проверьте права владельца токена. Для плана нужны чтение источника и приёмника; для применения — запись в приёмник. Как выдаются права. |
Проверка подключения выводит FAILED: | Это ответ проверки сервером Holkas. Исправьте параметры базы или доступ к ней с сервера; порядок диагностики. |
| План завершился с ошибкой | Откройте операцию и журнал, проверьте тип и имя объекта, подключения и Git ref. Ноль команд при ошибке не означает совпадение баз. |
| CLI перестал ждать, а результат неясен | Выполните holkas operation <номер> и holkas log <номер> --tail 20. Не запускайте перенос повторно, пока не выяснили исход первого. |
После разового запуска отзовите токен в той же карточке «Токены доступа». Уберите его из окружения: unset HOLKAS_API_KEY в Bash или Remove-Item Env:HOLKAS_API_KEY в PowerShell. Закрытие терминала очищает его сеанс, но само по себе не отзывает токен на сервере.
Проверка этой инструкции: архивы CLI 0.1.20 сверены с SHA256SUMS; Linux-клиент прошёл вход, построение плана, просмотр операции и журнала, выгрузку ZIP на учебном сервере. Скриншоты сняты с этих операций. Windows-архив проверен по сумме и составу; что проверено в PowerShell — в разделе о Windows.
Все параметры, манифесты, описатели, подтверждения и скачивание файлов — в справочнике команд CLI.