Dizajn CLI-ja za AI agente: JSON, izlazni kodovi i čekanje

CLI za AI agente nije samo alat naredbenog retka za ljude koji se slučajno može pozvati iz modela. On je operativni protokol. Agentu su potrebni deterministički ulazi, strukturirani izlazi, smisleni izlazni kodovi, stabilne kategorije pogrešaka i način čekanja da asinhrona infrastruktura dosegne završno stanje.

Bez tog ugovora agent mora zaključivati o uspjehu na temelju proze poput „implementacija je pokrenuta”. Takav je zaključak opasan jer prihvaćeni zahtjev kasnije može neuspjeti tijekom builda, provjera zdravlja, pokretanja containera ili preusmjeravanja prometa.

Zašto je opasno nagađati da je implementacija uspjela?

Većina infrastrukturnih operacija je asinhrona. API može prihvatiti implementaciju i vratiti ID u nekoliko milisekundi, dok stvarni build traje nekoliko minuta. Ako agent prijavi uspjeh u trenutku prihvaćanja, svaki se sljedeći korak temelji na pogrešnoj pretpostavci.

Razmotrite razliku:

Događaj	Što dokazuje	Što ne dokazuje
Zahtjev prihvaćen	Platforma je razumjela zahtjev	Kod je izgrađen
Build dovršen	Stvorena je slika ili artefakt	Aplikacija se pokrenula
Provjera zdravlja prošla	Nova instanca odgovorila je kako se očekuje	Poslovni procesi funkcioniraju
Promet preusmjeren	Izdanje je postalo aktivno	Ostat će zdravo
Promatranje dostupnosti	Servis je i dalje dohvatljiv	Svaka značajka radi ispravno

Čovjek može primijetiti razliku na nadzornoj ploči. Agentu koji radi putem teksta ta razlika mora biti ugrađena u sučelje.

Ugovor naredbi u Dockupu razdvaja stavljanje u red čekanja od dovršetka. deploy bez --wait odmah vraća rezultat s waited:false; deploy s --wait blokira dok ne nastupi uspjeh, pogreška ili istek vremena:

dockup deploy production/api --wait --json

Zadano vremensko ograničenje iznosi 900 sekundi. Naredba završava s 0 samo nakon uspješnog završnog stanja. U slučaju neuspješnog rezultata završava s kodom različitim od nule i kodom deploy_failed ili deploy_timeout.

Što strukturirani JSON CLI pruža AI agentu?

Strukturirani JSON zamjenjuje tumačenje proze imenovanim poljima. Agent može izravno pronaći status, deploymentId, target ili code, umjesto da ovisi o interpunkciji, bojama, širini stupaca ili formulaciji.

Uspješan rezultat može se obraditi kao podaci:

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

Pogreška koristi isti transportni oblik:

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

Važno pravilo dizajna jest da se JSON zapisuje u stdout, dok upozorenja koja ne smiju pokvariti parsiranje idu u stderr. Logovi u follow načinu koriste NDJSON — jedan JSON objekt po retku — pa pozivatelj može postupno obrađivati tok bez čekanja na jedan golemi niz.

Dockup primjenjuje --json na cijelu površinu svojih naredbi. Uz 135 naredbi, zahtijevati od agenta da zastavice izvodi iz pamćenja bilo bi krhko. CLI referenca i zapakirana vještina pružaju upute za naredbe usklađene s verzijom koje agent treba slijediti.

Važno svojstvo dizajna nije domišljato otkrivanje naredbi. Važno je da agent prima aktualne, strukturirane operativne upute i da ne izmišlja zastavicu na temelju starog prompta.

Kako stvarni izlazni kodovi upravljaju automatizacijom implementacije?

Izlazni kod operacijskog sustava najprenosiviji je signal uspjeha dostupan shell skriptama, CI runnerima i coding agentima. Izlaz 0 znači da je naredba ostvarila svoj definirani rezultat. Kod različit od nule znači da pozivatelj mora prijeći na oporavak, eskalaciju ili prekid.

Ovaj je isječak namjerno jednostavan:

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

Ne pretražuje stdout u potrazi za riječju „success”. Ne pretpostavlja da HTTP 202 znači da je produkcija spremna. Definiciju uspjeha prepušta CLI-ju i prosljeđuje pogrešku nadređenom procesu.

Stvarni izlazni kodovi jednako su važni za jednokratne naredbe unutar containera. Dockupova PRO naredba exec vraća stdout, stderr i stvarni izlazni kod naredbe:

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

Agent tako može razlikovati dovršenu migraciju od naredbe koja se samo pokrenula. To je temeljno načelo zaštitnih mehanizama za AI agente u produkciji.

Kako čekanje završnog stanja zamjenjuje krhki polling?

Ručno napisane polling petlje uvode skrivene odluke o pravilima: koliko često provjeravati stanje, koja su stanja završna, koliko dugo čekati, treba li prolazna mrežna pogreška ponovno pokrenuti mjerač vremena i što učiniti kada se container ponovno pokrene.

Agent će osobito vjerojatno pogrešno donijeti te odluke jer možda ne poznaje cjelokupni stroj stanja platforme. Platforma treba upravljati semantikom čekanja.

Dockup pruža dva korisna obrasca:

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

deploy --wait izričito čeka. push prema zadanim postavkama čeka nakon slanja i pokretanja izdanja; --no-wait služi za isključivanje čekanja. Obje naredbe vraćaju izlazni kod koji odražava završni rezultat.

Praćenje logova slijedi istu ideju:

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

Tok završava kada build dosegne uspjeh ili neuspjeh. Završni NDJSON objekt označava done:true, a neuspjeli build završava s kodom različitim od nule. Pozivatelj ne mora implementirati drugu polling petlju.

Za dostupnost aplikacije nakon implementacije, Dockupova naredba uptime vraća provjere na razini minute, prosječno vrijeme odgovora i p95:

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

Čekanje i nadzor odvojeni su koncepti. --wait odgovara na pitanje je li ova implementacija dosegla završni rezultat; uptime pokazuje kako se pokrenuti servis ponašao tijekom vremena.

Koje kodove pogrešaka agent treba razumjeti?

Stabilne kategorije pogrešaka omogućuju agentu da poduzme ograničenu radnju bez tumačenja svake moguće poruke. Dockup izlaže kodove kao što su:

Kod pogreške	Značenje	Siguran odgovor agenta
not_logged_in	Nema upotrebljivog tokena	Zaustaviti se i zatražiti autentikaciju
not_linked	Ne postoji odredište .dockup za push	Razriješiti odredište ili ga proslijediti
no_target	Servis se ne može identificirati	Pokrenuti services --json
needs_confirm	Destruktivnoj radnji nedostaje odobrenje	Zatražiti čovjeka
deploy_trigger_failed	Implementaciju nije moguće pokrenuti	Prijaviti API pogrešku
deploy_failed	Build ili implementacija završili su neuspjehom	Pročitati build logove
deploy_timeout	Radnja je još u tijeku nakon isteka vremena čekanja	Prijaviti nesigurnost ili namjerno produljiti čekanje

Poruka pogreške i dalje je koristan kontekst, ali kod upravlja prvim grananjem. Automatizacija je tako otporna na jasniju formulaciju ili lokalizaciju.

Potvrda je također dio protokola. Destruktivna naredba ne bi smjela nečujno nastaviti samo zato što je pozivatelj neinteraktivan. Dockup odbija takve operacije bez --yes i vraća needs_confirm. Autonomni agent tada vidi pitanje, a ne prepreku koju treba zaobići.

Sigurnosni je model dodatno objašnjen u tekstu najbolje sigurnosne prakse.

Koji je minimalni ugovor za CLI spreman za produkciju?

CLI za AI agente spreman za produkciju treba ispunjavati mali, ali strog ugovor:

1. Svaka operacija čitanja i pisanja ima strojno čitljiv izlaz.
2. Pogreška proizvodi izlaz procesa različit od nule.
3. Asinhrone mutacije mogu čekati dokumentirano završno stanje.
4. Tajne vrijednosti nikad se ne vraćaju naredbama za čitanje.
5. Destruktivne radnje zahtijevaju izričitu potvrdu.
6. Pogreške imaju stabilne kodove pogodne za grananje.
7. Paket CLI-ja i upute za agenta ostaju usklađeni s verzijom.
8. Mutacije se bilježe u revizijskom tragu.

Dockupova vještina pretvara ta pravila u zadano ponašanje za Claude Code i Codex. Agentu nalaže korištenje JSON-a, autentikaciju pomoću DOCKUP_TOKEN, otkrivanje točnih odredišta, implementaciju s --wait, zaštitu vjerodajnica i zaustavljanje na needs_confirm.

Usporedite ovaj model sa širim konceptima u tekstu agent skills u odnosu na MCP. Vještina pruža operativno znanje; CLI ostaje izvršno sučelje čiji izlazni status i izlaz definiraju istinu.

Testna matrica za naredbu namijenjenu agentu

Prije nego što bilo koju infrastrukturnu naredbu izložite agentu, testirajte više od uspješnog scenarija:

Test	Očekivano ponašanje
Valjan zahtjev	JSON rezultat i izlaz 0
Nevaljan token	Stabilan kod autentikacije i izlaz različit od nule
Nepoznato odredište	Stabilan kod odredišta i bez mutacije
Dugotrajna implementacija	Čeka do završnog stanja ili isteka vremena
Neuspjela implementacija	Izlaz različit od nule i dijagnostički ID implementacije
Nedostaje odobrenje za destruktivnu radnju	needs_confirm, bez brisanja
Čitanje tajne	Metapodaci ključa vidljivi, vrijednost maskirana
Upozorenje tijekom JSON izlaza	Upozorenje na stderr, valjan JSON na stdoutu

Ova je matrica vrjednija od dotjeranog indikatora napretka. Ljudsko oblikovanje može se dodati naknadno; deterministički strojni ugovor ne može se pouzdano rekonstruirati nakon činjenice.

Dockupova dokumentacija za CLI prikazuje konkretne naredbe iza ovog modela, dok razvoj uz pomoć AI-ja objašnjava širi pomak od ručnog korištenja alata prema tijekovima rada kojima upravljaju agenti.

Promatranje sustava smatrajte dijelom ugovora naredbe

Mutacija namijenjena agentu treba vraćati identifikatore koji omogućuju kasniju istragu. Odgovor implementacije treba sadržavati odredište i ID implementacije; stvorena baza podataka treba imati stabilan slug; snimka volumena treba imati svoj ID snimke. Bez tih referenci agent može opisati događaj, ali ne može pouzdano pregledati stanje, ponoviti radnju ili je poništiti.

Revizijski trag upotpunjuje ugovor. Strukturirani izlaz objašnjava jedno pozivanje, dok revizijski zapisi povezuju više pozivanja tijekom vremena. Zajedno operaterima omogućuju utvrditi je li agent djelovao nad namijenjenim resursom i je li se kasnija naredba za oporavak odnosila na isti produkcijski događaj.

Sučelje neka bude dosadno

Pouzdan CLI za AI agente treba biti predvidljiv u slučaju uspjeha, pogreške, isteka vremena i ponovnog pokušaja.

Završni test sučelja

CLI za AI agente mora izvještavati istinito o neuspjehu.

Uvedite tijek rada u produkciju

Najprije testirajte ugovor iz shella: provjerite parsiranje JSON-a, uspješan izlaz, namjerno izazvanu pogrešku, istek vremena i blokiranu destruktivnu operaciju prije nego što agentu delegirate pristup produkciji.

npm install -g dockup-cli
dockup skill install

Prva naredba instalira CLI. Druga instalira odgovarajuću Dockupovu vještinu za Claude Code i Codex. Započnite besplatno na app.dockup.ai.

Često postavljana pitanja

Što CLI čini prikladnim za AI agente?

Potreban je strukturirani izlaz, stvarni izlazni kodovi, čekanje završnog stanja, stabilni kodovi pogrešaka, maskiranje tajni i izričita potvrda destruktivnih operacija.

Zašto je JSON bolji od CLI izlaza oblikovanog za ljude kada je riječ o agentima?

JSON pruža stabilna imena polja i tipove podataka. Agent ne mora zaključivati značenje iz boja, tablica, interpunkcije ili promjenjive proze.

Zašto prihvaćeni zahtjev za implementaciju nije isto što i uspjeh?

Prihvaćanje samo dokazuje da je platforma stavila operaciju u red čekanja. Naknadni build, pokretanje, provjera zdravlja i preusmjeravanje prometa i dalje mogu neuspjeti.

Koje je zadano vremensko ograničenje čekanja na Dockupovu implementaciju?

Zadano vremensko ograničenje za dockup deploy --wait iznosi 900 sekundi i može se promijeniti dokumentiranom opcijom --timeout.

Kako agent treba reagirati na needs_confirm?

Treba se zaustaviti i zatražiti izričito odobrenje. Kod znači da je tražena radnja destruktivna i da namjerno nije izvršena.