Дизайн на CLI за AI агенти: JSON, exit кодове и изчакване

CLI за AI агенти не е просто инструмент за командния ред, предназначен за хора, който случайно може да бъде извикан от модел. Той е operational protocol. Агентът се нуждае от детерминистични входове, структурирани изходи, смислени exit кодове, стабилни категории грешки и начин да изчака до достигането на финално състояние от асинхронната инфраструктура.

Без такъв договор агентът е принуден да извежда успех от текст като „deployment-ът започна“. Това заключение е опасно, защото приета заявка може по-късно да се провали по време на build, health checks, стартиране на container или превключване на трафика.

Защо предполагаемият успех на deployment е опасен?

Повечето инфраструктурни операции са асинхронни. Един API може да приеме deployment и да върне ID за милисекунди, докато реалният build отнеме няколко минути. Ако агентът отчете успех в момента на приемане, всяка следваща стъпка ще се основава на невярна предпоставка.

Разликата е следната:

Събитие	Какво доказва	Какво не доказва
Заявката е приета	Платформата е разбрала заявката	Кодът е компилиран
Build-ът е завършил	Създаден е image или artifact	Приложението е стартирало
Health gate-ът е преминат	Новият instance е отговорил според изискванията	Business flow-овете работят
Трафикът е превключен	Release-ът е станал активен	Ще остане здрав
Наблюдение на uptime	Услугата остава достъпна	Всяка функционалност работи коректно

Човек може да забележи разликата в dashboard. Агент, който работи чрез текст, се нуждае от тази информация, кодирана в интерфейса.

Договорът на Dockup за командите разделя поставянето на опашка от завършването. Deploy без --wait се връща незабавно с waited:false; deploy с --wait блокира до успех, грешка или timeout:

dockup deploy production/api --wait --json

Timeout-ът по подразбиране е 900 секунди. Командата завършва с 0 само след успешно terminal state. При резултат, различен от успех, тя завършва с различен от нула код и deploy_failed или deploy_timeout.

Какво дава един структуриран JSON CLI на AI агент?

Структурираният JSON заменя интерпретацията на текст с именувани полета. Агентът може директно да намери status, deploymentId, target или code, вместо да зависи от пунктуация, цветове, ширина на колони или формулировки.

Успешният резултат може да бъде обработен като данни:

{
  "ok": true,
  "target": "production/api",
  "deploymentId": "dep_123",
  "waited": true,
  "status": "success",
  "durationMs": 142381,
  "url": "https://api.dockup.tech"
}

При грешка се използва същата transport структура:

{
  "ok": false,
  "error": "Deployment failed",
  "code": "deploy_failed"
}

Важно правило в дизайна е JSON да се записва в stdout, а предупрежденията, които не трябва да повреждат parsing-а, да отиват в stderr. Log-овете във follow mode използват NDJSON — един JSON обект на ред — така че извикващата страна да може да обработва потока постепенно, без да чака един огромен масив.

Dockup прилага --json за всички свои команди. При 135 команди изискването агентът да извежда флагове от памет би било ненадеждно. CLI reference-ът и пакетираният skill предоставят инструкциите за команди, съобразени с конкретната версия, които агентът трябва да следва.

Важното свойство на дизайна не е интелигентното откриване. Важно е агентът да получава актуални, структурирани оперативни указания и да не измисля флаг въз основа на стар prompt.

Как реалните exit кодове управляват deployment automation?

Exit кодът на операционната система е най-преносимият сигнал за успех, достъпен за shell скриптове, CI runner-и и coding агенти. Exit 0 означава, че командата е постигнала дефинирания резултат. Различен от нула код означава, че извикващата страна трябва да премине към recovery, ескалация или прекратяване.

Този shell фрагмент нарочно е обикновен:

if dockup deploy production/api --wait --json > result.json; then
  echo "deployment reached success"
else
  dockup logs production/api --build --json
  exit 1
fi

Той не търси думата “success” в stdout. Не приема, че HTTP 202 означава, че production е готов. Вместо това оставя CLI да определи какво е успех и предава грешката към родителския процес.

Реалните exit кодове са също толкова важни и за еднократни команди в container. PRO командата exec на Dockup връща stdout, stderr и реалния exit код на командата:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Така агентът може да различи завършила миграция от команда, която само е стартирала. Това е основен принцип на production guardrails за AI агенти.

Как изчакването до terminal state заменя ненадеждното polling поведение?

Ръчно написаните polling цикли въвеждат скрити policy решения: колко често да се прави polling, кои състояния са terminal, колко дълго да се чака, дали временна network грешка трябва да нулира таймера и какво да се прави при рестартиране на container.

Агентът е особено склонен да сгреши в тези решения, защото може да не познава пълната state machine на платформата. Платформата трябва да управлява семантиката на изчакването.

Dockup предоставя два полезни модела:

dockup deploy production/api --wait --timeout 1800 --json
dockup push --json

deploy --wait изчаква изрично. push изчаква по подразбиране след push-ването и задействането на release-а; --no-wait изключва това поведение. И двете команди връщат exit код, който отразява terminal резултата.

Следването на log-ове следва същата идея:

dockup logs production/api --build -f --json

Потокът приключва, когато build-ът достигне success или failure. Финален NDJSON обект маркира done:true, а при неуспешен build командата завършва с различен от нула код. Извикващата страна не се нуждае от втора polling имплементация.

За наличността на приложението след deployment командата за uptime на Dockup връща проверки на ниво минута, средно време за отговор и p95:

dockup uptime production/api --hours 24 --json

Изчакването и monitoring-ът са отделни понятия. --wait отговаря дали този deployment е достигнал terminal резултат; uptime показва как се е държала работещата услуга във времето.

Кои error кодове трябва да разбира един агент?

Стабилните категории грешки позволяват на агента да предприеме ограничено и предвидимо действие, без да интерпретира всяко възможно съобщение. Dockup предоставя кодове като:

Error code	Значение	Безопасна реакция на агента
not_logged_in	Няма използваем token	Спира и изисква authentication
not_linked	Няма .dockup target за push	Разрешава target-а или го подава изрично
no_target	Service-ът не може да бъде идентифициран	Изпълнява services --json
needs_confirm	На destructive action-а липсва approval	Пита човек
deploy_trigger_failed	Deployment-ът не може да стартира	Докладва API грешката
deploy_failed	Build-ът или deploy-ят са достигнали failure	Прочита build log-овете
deploy_timeout	Все още се изпълнява след изтичане на лимита за изчакване	Докладва несигурност или умишлено удължава изчакването

Съобщението за грешка остава полезен контекст, но кодът определя първия клон на логиката. Това прави automation-а устойчив при по-ясни формулировки или localization.

Confirmation-ът също е част от протокола. Destructive command не трябва да продължава безшумно само защото извикващата страна е non-interactive. Dockup отказва такива операции без --yes и връща needs_confirm. Автономният агент вижда въпрос, а не преграда, която трябва да заобиколи.

Моделът за безопасност е разгледан по-подробно в най-добрите практики за security.

Какъв е минималният договор за production-ready CLI?

Един production-ready CLI за AI агенти трябва да спазва малък, но строг договор:

1. Всяка read и write операция има machine-readable output.
2. При грешка процесът завършва с различен от нула exit код.
3. Асинхронните мутации могат да изчакват до документирано terminal state.
4. Secret стойностите никога не се връщат от read команди.
5. Destructive actions изискват изрично confirmation.
6. Грешките имат стабилни кодове, подходящи за branching.
7. CLI пакетът и инструкциите за агента остават съгласувани с версията.
8. Мутациите се записват в audit trail.

Skill-ът на Dockup превръща тези правила в поведение по подразбиране за Claude Code и Codex. Той инструктира агента да използва JSON, да се удостоверява с DOCKUP_TOKEN, да открива точните target-и, да deploy-ва с --wait, да защитава credentials и да спира при needs_confirm.

Сравнете този модел с по-широките концепции в agent skills срещу MCP. Skill-ът предоставя operational knowledge; CLI остава изпълнимият интерфейс, чиито exit status и output определят истината.

Test matrix за команда, предназначена за агент

Преди да предоставите инфраструктурна команда на агент, тествайте повече от happy path:

Test	Очаквано поведение
Валидна заявка	JSON резултат и exit 0
Невалиден token	Стабилен auth код и различен от нула exit
Непознат target	Стабилен target код и липса на мутация
Дълго изпълняващ се deploy	Изчаква до terminal state или timeout
Неуспешен deploy	Различен от нула exit плюс deployment ID за диагностика
Липсващо destructive approval	needs_confirm, без изтриване
Read на secret	Метаданните на ключа са видими, стойността е маскирана
Предупреждение по време на JSON output	Предупреждението е в stderr, stdout съдържа валиден JSON

Тази matrix е по-ценна от изпипан progress spinner. Човешкото форматиране може да бъде добавено отгоре; детерминистичен machine contract не може да бъде възстановен със задна дата.

Документацията за Dockup CLI показва конкретните команди зад този модел, а AI-powered development обяснява по-широкия преход от ръчно използване на инструменти към workflow-и, управлявани от агенти.

Приемайте observability като част от договора на командата

Мутация, предназначена за агент, трябва да връща идентификатори, които правят по-нататъшното разследване възможно. Deployment response-ът се нуждае от target и deployment ID; създадената database — от стабилен slug; snapshot-ът на volume — от snapshot ID. Без тези референции агентът може да опише събитие, но не може надеждно да го инспектира, повтори или отмени.

Audit trail-ът завършва договора. Структурираният output обяснява едно извикване, докато audit записите свързват множество извиквания във времето. Заедно те позволяват на операторите да отговорят дали агентът е работил с правилния resource и дали последваща recovery команда се е отнасяла до същото production събитие.

Поддържайте интерфейса прост

Надеждният CLI за AI агенти трябва да се държи предвидимо при success, failure, timeout и retry.

Финален тест на интерфейса

CLI за AI агенти трябва да се проваля честно.

Въведете workflow-а в production

Първо тествайте договора от shell: проверете parsing-а на JSON, успешния exit, принудителна грешка, timeout и блокирана destructive операция, преди да делегирате достъп до production.

npm install -g dockup-cli
dockup skill install

Първата команда инсталира CLI. Втората инсталира съответстващия Dockup skill за Claude Code и Codex. Започнете безплатно от app.dockup.ai.

ЧЗВ

Какво прави един CLI подходящ за AI агенти?

Необходими са structured output, реални exit кодове, изчакване до terminal state, стабилни error кодове, маскиране на secret стойности и изрично confirmation за destructive operations.

Защо JSON е по-добър от CLI output, форматиран за хора, при работа с агенти?

JSON предоставя стабилни имена и типове на полетата. Агентът не трябва да извежда значението от цветове, таблици, пунктуация или променящ се текст.

Защо приета deployment заявка не е равна на успех?

Приемането доказва само, че платформата е поставила операцията на опашка. Последващите build, startup, health gate и traffic cutover все още могат да се провалят.

Какъв е timeout-ът по подразбиране за изчакване при deployment в Dockup?

Timeout-ът по подразбиране за dockup deploy --wait е 900 секунди и може да бъде променен с документираната опция --timeout.

Как трябва агентът да реагира на needs_confirm?

Той трябва да спре и да поиска изрично одобрение. Кодът означава, че заявеното действие е destructive и умишлено не е изпълнено.