CLI

Как человек и агент работают с ai_stp CLI: JSON-конверт, mutability и группы команд.

CLI

CLI — рабочая поверхность продукта. Он обнаруживает факты, ведёт паспорта, выбирает состав и просит provider харнесса применить план. Сайт показывает каталог и аккаунт. Нативное состояние harness он не пишет.

Каждую команду, которую человек копирует из этого справочника, запускайте с --json. CLI печатает ровно один конверт в stdout и больше ничего.

Как читать конверт

При ok: true результат в data. warnings всё равно стоит показать. При ok: false error.code — стабильный код из закрытого реестра; next_actions называет разумную следующую команду, а не разрешение.

Не угадывать следующий шаг по классу кода выхода. Повторять вызов только если конверт говорит retryable: true. После неподтверждённого таймаута сначала читайте статус, а не повторяйте apply.

Mutability и confirmation

Эти два поля отвечают на разные вопросы.

`mutability`	Смысл
`read`	наблюдает; ничего не создаёт
`plan`	записывает проверяемый план или снимок; target не меняет
`apply`	меняет состояние
`destructive`	уничтожает идентичность или управляемые байты; всегда отдельное решение

`confirmation`	Смысл
`none`	лишнего токена нет; это не «можно запускать не спросив»
`explicit_flag`	передать флаг из дескриптора, обычно `--confirm`
`plan_digest`	передать `--expected-plan-digest` неизменённого плана

Команда чтения на свежей установке возвращает типизированную пустоту. Она не запускает молча device init.

Machine help — это парсер

Повседневное обнаружение:

ai-stp task intents --json

Expert: полный реестр этой установки:

ai-stp help --agent --json

Документация группирует команды, чтобы человек нашёл страницу. Если страница и CLI расходятся, следуйте CLI.

Полный список по одной строке на команду — карта команд.

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

Группа	Страница	Когда открывать
Наблюдение	Наблюдение	первый запуск, здоровье, machine help
Конфигурация	Конфигурация	значения, которые эта установка должна соблюдать
Телеметрия	Телеметрия установки	необязательный анонимный ping установки
Устройство	Устройство	идентичность этой установки
Паспорта	Паспорта	факты разработчика и устройства
Вход	Вход	сессия аккаунта и `link web`
Согласие	Согласие	непроверенные издатели и major-линии
Проект	Проект	discover, индекс, символы, паспорт проекта
Toolchain	Toolchain	управляемые инструменты и обзор harness
Программа harness	Программа harness	бинарник harness, не сетап
Agent Skill	Agent Skill CLI	skill самого CLI, не kind `skill`
Реестр	Реестр	поиск в каталоге, fetch, локальные port
Компонент	Команды компонента	discover → паспорт → публикация
Выбор	Выбор	eligibility, proposal, отчёты
Установка	Установка	intent install; expert recover/resume остаются
Target	Target	ежедневный статус, diff, backup, именованный rollback
Setup	Команды сетапа	compose, импорт, update, публикация
Provider	Provider	бинарник, который пишет нативное состояние
Синхронизация	Синхронизация	частный поток аккаунта
Доступ	Доступ	доступ к major-линии
Жалобы	Жалобы	закрытые жалобы
Owner	Owner	серверные объекты, которыми вы владеете
Publication	Publication	attest, plan, confirm
Eval	Eval	локальная эталонная оценка

Рабочий цикл

task intents --json
→ task start --intent <shipped> --idempotency-key <key> --json
→ follow continuations (исполнять argv только когда actor равен cli)
→ сообщить payload verification

Expert leaves (install plan / approve / apply) остаются для recovery. Повседневные install, change и switch сливают эти шаги in-process под соответствующим intent.

Агент пропускает шаг, только если предыдущий конверт уже сделал его ненужным. Механическую проверку он не пропускает.

Чего CLI не делает

не вызывает model API и не просит ключ модели;
не пишет target harness сам — это делает только public provider;
не кладёт секреты, тела .env и токены в паспорт;
не считает author_verified доказательством безопасности версии компонента.

Типичные отказы

Что видно	Что это значит	Что делать
мутирующая команда без `--json`	в stdout смешался человеческий текст	добавить `--json` и читать один конверт
stale plan	байты плана изменились	построить новый план, показать, подтвердить снова
нет confirmation	требовался `explicit_flag` или `plan_digest`	прочитать дескриптор; не выдумывать имя флага
команды нет в machine help	этой установки её нет	остановиться; не подменять похожей командой

Первый запуск связным текстом — Быстрый старт для человека. Ритуал сессии для агента — Быстрый старт для ИИ-агента.