soulctl

Клиентский CLI оператора — тонкая обёртка над Operator API Keeper-а. Первичный интерфейс оператора — OpenAPI и MCP; soulctl — удобный CLI поверх тех же HTTP-эндпоинтов, не отдельный протокол.

Аутентификация

soulctl работает от имени оператора (Archon) по JWT. Credentials хранятся в ~/.config/soul-stack/credentials.yaml (два поля: keeper_url и токен оператора):

soulctl archon login     # сохранить keeper_url + JWT (валидируется ping-ом)
soulctl archon whoami     # текущий AID + permissions из claims токена
soulctl archon logout     # удалить credentials.yaml

keeper_url указывает на Operator API Keeper-а (HTTP-listener, по умолчанию порт 8080). Глобальные флаги: --output table|json|yaml (-o) и --config (путь к альтернативному credentials-файлу).

Группы команд

soulctl собран из семи верхних групп:

Группа	Назначение
`incarnation`	операции над инкарнациями (runtime-инстансами сервисов)
`souls`	операции над управляемыми душами
`soul`	одиночные действия на конкретном агенте
`errand`	реестр одиночных задач (Errand): list / get / cancel
`archon`	аутентификация и идентичность оператора
`push-providers`	управление параметрами SSH-плагинов push-режима
`run`	запуск scenario / ad-hoc cmd / push с универсальным таргетингом

incarnation

soulctl incarnation list                      # перечислить инкарнации
soulctl incarnation get <name>                # spec / state / status / covens
soulctl incarnation run <name> <scenario>     # запустить scenario на инкарнации
soulctl incarnation history <name>            # история изменений состояния
soulctl incarnation check-drift <name>        # проверка drift инкарнации

souls / soul

soulctl souls list                            # перечислить зарегистрированных агентов
soulctl souls get <sid>                       # показать агента по SID
soulctl souls ssh-target set <sid> ...        # per-host SSH-реквизиты push-режима
soulctl souls ssh-target bulk-set ...         # массовая привязка SSH-провайдера в Coven
soulctl soul exec <sid> ...                   # одиночный модуль на конкретном агенте (Errand)

errand

soulctl errand list                           # перечислить Errand-ы с фильтрами
soulctl errand get <errand_id>                # состояние Errand-а
soulctl errand cancel <errand_id>             # отменить in-flight Errand

push-providers

soulctl push-providers create <name> ...      # создать запись Push-Provider-а
soulctl push-providers list                   # перечислить
soulctl push-providers get <name>             # прочитать
soulctl push-providers update <name> ...      # заменить params (replace-семантика)
soulctl push-providers delete <name>          # удалить

run

Зонтик для батчевых прогонов с единым таргетингом:

soulctl run scenario <service>/<scenario>     # батчевый scenario-прогон над инкарнациями
soulctl run cmd '<command>'                   # ad-hoc shell-команда на N хостов
soulctl run push <destiny@ref>                # push-применение destiny через SSH-провайдер

Обработка ошибок

soulctl приводит HTTP-ошибки Operator API к понятной форме: 401 → подсказка soulctl archon login, 403 → отсутствие permission, 404 → not found, 5xx → keeper error.

Установка

soulctl deb/rpm-пакетом не поставляется. Берётся из релизного исполняемого файла или сборки (make build). См. Из бинарных релизов и Из исходников.