brt — обзор CLI

brt — единственный исполняемый developer CLI платформы. Он связывает TypeScript-проект, workspace на сервере и два независимых target: dev для быстрой разработки и production для явного deploy.

@holocronlab/botruntime-adk — библиотека генерации и runtime, которую вызывает brt внутри agent workflow. Это не второй CLI и не отдельная команда, которую нужно устанавливать или запускать рядом.

Главная граница проста:

• brt dev запускает код локально и подключает к нему отдельного dev-бота через tunnel;
• brt deploy --adk собирает agent-проект и обновляет production-бота;
• brt deploy --adk --watch — явно выбранный постоянный cloud redeploy, а не скрытая семантика команды dev.

Как связаны проект и окружения

agent.json — каноническая production-привязка агентного проекта, которую можно хранить в Git. agent.local.json хранит локальные настройки и привязку dev-бота и не должен попадать в Git. bot.json остаётся совместимым fallback для классических и старых проектов; в новом агентном проекте он не может переопределить agent.json.

Командная карта

Практические сигнатуры и основные флаги находятся в справочнике; полный набор конкретной версии печатает brt <command> --help. Пошаговая модель окружений и разбор ошибок — на странице «Рабочий цикл: dev → production».

brt traces читает metadata-only трейсы обязательного conversation. В production команда берёт canonical workspace и bot из project link, в dev — проверенный opaque runtime target, созданный brt dev. Оба режима аутентифицируются PAT выбранного профиля и не позволяют path, query или header переопределить его workspace authority. Ответ ограничен типизированным allowlist: prompts, сообщения, model responses, tool input/output, документы и raw errors команда не получает и не печатает.

brt conversations list показывает только bounded metadata диалогов: ID, timestamps, channel, integration и message count. brt conversations show <id> строит timeline из той же типизированной trace-проекции. Production/dev target, и PAT authority имеют ту же fail-loud семантику, что у brt traces. Conversation tags, сообщения и payload в вывод не попадают.

brt eval [name] (или явный brt eval run [name]) синхронизирует локальный eval manifest/fixtures, провижинит first-party Chat при необходимости и запускает задеплоенный builtin_eval_runner; brt eval runs читает hosted history. Production использует canonical numeric bot и сохранённый per-bot key, dev — PAT, суженный attested opaque runtime bot. Вывод содержит только typed verdict, timing и assertion metadata: prompts, сообщения, model responses, evidence и raw workflow/evaluator errors не печатаются. Повторные независимые runs включаются через --repeat, bounded concurrency — через --max-concurrency, а CI-порог — через --min-pass-rate.

Профиль и авторизация

Профиль хранит endpoint, выбранный воркспейс и PAT в ~/.brt/profiles.json. brt login по умолчанию запускает device authorization в браузере и обращается к облачной платформе https://botruntime.ru.

Для ручной вставки PAT используйте --no-device. Для CI передайте --token и --workspace-id. Необязательный --api-url нужен только для прокси, staging и разработки платформы. В обычном входе его указывать не нужно.

brt login
brt profiles active
brt profiles use team-b

Токен профиля и per-bot key решают разные задачи:

brt logs использует workspace/profile PAT и вложенный маршрут конкретного бота. Тот же device-login профиль, которым выполняется deploy, сразу подходит для чтения логов; per-bot key для этой команды не нужен.

Первый deploy --adk может сам создать production-бота и безопасно сохранить выданный per-bot key. Для существующего бота используйте brt link:

export BOT_ID='42'
printf '%s' "$BOT_KEY" | brt link --bot-id "$BOT_ID" --key-stdin

CLI сначала сохраняет ключ и только затем link-файл: аварийный обрыв не оставит проект с привязкой, для которой потеряны данные доступа.

Dev и production

brt dev создаёт отдельный dev target в облачной платформе и запускает код на вашей машине. Production-бот при этом не изменяется.

brt deploy --adk собирает проект и обновляет production target. Связь проекта с ботом хранится в agent.json или bot.json.

Основной путь

# 1. отдельный dev-бот + локальный процесс/tunnel
brt dev

# 2. из второго терминала — конфигурация именно dev-бота
printf '%s' "$DEV_EXTERNAL_API_KEY" | brt secret set EXTERNAL_API_KEY --dev

# 3. первый production deploy создаёт target и загружает текущий код
brt deploy --adk --name "Мой бот"

# 4. production-интеграция настраивается без --dev
printf '{"botToken":"%s"}' "$PROD_TELEGRAM_TOKEN" \
  | brt integrations install botruntime/telegram@1.1.3 --config-stdin
export PROD_WEBHOOK_ID='wh_replace_from_install_output'
brt integrations register "$PROD_WEBHOOK_ID"

# 5. обязательный второй deploy включает новое состояние Cloud в bundle
brt deploy --adk

install/register меняют интеграции и обновляют локальное production-отражение зависимостей, но не генерируют и не загружают bundle. Приёмочная проверка production начинается после второго deploy. В dev такое обновление с --dev замечает уже запущенный watcher и сам повторяет генерацию.

Для Telegram используйте разные dev/prod Bot API токены: Telegram держит один активный webhook на токен, поэтому разделить только ботов внутри платформы недостаточно.

Гарантии безопасности

• каждый dev и deploy --adk сверяет точное authoritative-состояние target с Cloud до генерации и сборки;
• dev --check остаётся read-only gate подготовленного dev target: не создаёт target и не исправляет drift;
• настройки, секреты и интеграции dev/prod изолированы;
• значения для config set, secret set и конфигурации интеграции читаются из stdin или файла, а не из value-аргумента;
• секретные поля схемы интеграции запечатываются сервером; обычный config хранится как JSONB и не должен содержать секреты;
• удаление таблиц, колонок или смена их типов требуют отдельного --allow-destructive-table-changes; общий -y/--confirm эту защиту не обходит.

Дальше