AI-agentin CLI-suunnittelu: JSON, exit-koodit ja odotus

AI-agentin CLI ei ole pelkkä ihmisille tarkoitettu komentorivityökalu, jota voi sattumalta kutsua mallista. Se on operatiivinen protokolla. Agentti tarvitsee deterministiset syötteet, rakenteiset tulosteet, merkitykselliset exit-koodit, vakaat virheluokat sekä tavan odottaa, että asynkroninen infrastruktuuri saavuttaa lopullisen tilan.

Ilman tätä sopimusta agentti joutuu päättelemään onnistumisen esimerkiksi tekstistä ”deployment started”. Tämä päättely on vaarallista, koska hyväksytty pyyntö voi myöhemmin epäonnistua buildin, health checkien, containerin käynnistyksen tai liikenteen vaihdon aikana.

Miksi arvattu julkaisun onnistuminen on vaarallista?

Useimmat infrastruktuurioperaatiot ovat asynkronisia. API voi hyväksyä julkaisun ja palauttaa tunnisteen millisekunneissa, vaikka varsinainen build kestää useita minuutteja. Jos agentti ilmoittaa onnistumisesta hyväksynnän kohdalla, kaikki myöhemmät vaiheet perustuvat väärään oletukseen.

Ero on seuraava:

Tapahtuma	Mitä se osoittaa	Mitä se ei osoita
Pyyntö hyväksytty	Alusta ymmärsi pyynnön	Koodi käännettiin
Build valmis	Image tai artifact luotiin	Sovellus käynnistyi
Health gate läpäisty	Uusi instanssi vastasi vaatimusten mukaisesti	Liiketoimintavirrat toimivat
Liikenne vaihdettu	Julkaisu aktivoitui	Se pysyy terveenä
Käytettävyyden seuranta	Palvelu on edelleen tavoitettavissa	Kaikki ominaisuudet toimivat

Ihminen voi huomata eron dashboardissa. Tekstin välityksellä toimivalle agentille ero on koodattava käyttöliittymään.

Dockupin komentokutsusopimus erottaa jonottamisen valmistumisesta. Ilman --wait-valitsinta suoritettu deploy palautuu heti arvolla waited:false; --wait-valitsimen kanssa suoritettu deploy estyy, kunnes tila on onnistunut, epäonnistunut tai aikakatkaistu:

dockup deploy production/api --wait --json

Oletusaikakatkaisu on 900 sekuntia. Komento palauttaa exit-koodin 0 vain onnistuneen terminaalitilan jälkeen. Jos tulos ei ole onnistunut, komento palauttaa nollasta poikkeavan koodin ja arvon deploy_failed tai deploy_timeout.

Mitä rakenteinen JSON-CLI tarjoaa AI-agentille?

Rakenteinen JSON korvaa proosatekstin tulkinnan nimetyillä kentillä. Agentti voi löytää suoraan kentät status, deploymentId, target tai code sen sijaan, että se olisi riippuvainen välimerkeistä, väreistä, sarakeleveydestä tai sanamuodoista.

Onnistunut tulos voidaan käsitellä datana:

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

Virhe käyttää samaa siirtorakennetta:

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

Tärkeä suunnittelusääntö on, että JSON kirjoitetaan stdoutiin, kun taas jäsennystä häiritsemättömät varoitukset ohjataan stderrille. Follow-tilan lokit käyttävät NDJSON-muotoa — yksi JSON-objekti riviä kohden — joten kutsuja voi käsitellä virtaa asteittain odottamatta yhtä suurta taulukkoa.

Dockup käyttää --json-valitsinta kaikissa komennoissaan. Kun komentoja on 135, agentin edellyttäminen valitsimien päättelemiseen muistinsa perusteella olisi hauraaa. CLI-referenssi ja paketoitu skill tarjoavat agentin käyttöön version mukaiset komento-ohjeet.

Tärkeä suunnitteluominaisuus ei ole nokkela discovery. Olennaista on, että agentti saa ajantasaiset ja rakenteiset toimintaohjeet eikä keksi vanhan promptin perusteella valitsinta, jota ei ole olemassa.

Miten oikeat exit-koodit ohjaavat julkaisun automaatiota?

Käyttöjärjestelmän exit-koodi on shell-skripteille, CI-ajureille ja coding agenteille käytettävissä oleva siirrettävin onnistumissignaali. Exit 0 tarkoittaa, että komento saavutti sille määritellyn lopputuloksen. Nollasta poikkeava koodi tarkoittaa, että kutsujan on siirryttävä palautukseen, eskalointiin tai lopettamiseen.

Tämä shell-fragmentti on tarkoituksella tylsä:

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

Se ei etsi stdoutista sanaa ”success”. Se ei oleta, että HTTP 202 -vastaus tarkoittaa tuotannon olevan valmis. Se jättää onnistumisen määrittelyn CLI:lle ja välittää virheen ylemmälle prosessille.

Oikeat exit-koodit ovat yhtä tärkeitä myös containerin sisällä suoritettaville kertaluonteisille komennoille. Dockupin PRO exec -komento palauttaa stdoutin, stderrin ja varsinaisen komennon exit-koodin:

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

Agentti voi siten erottaa valmistuneen migraation komennosta, joka vain käynnistyi. Tämä on AI-agenttien tuotantoturvarajoitteiden perusperiaate.

Miten terminaalitilan odotus korvaa hauraan pollauksen?

Itse kirjoitetut polling-loopit tuovat mukanaan piileviä politiikkapäätöksiä: kuinka usein kysely tehdään, mitkä tilat ovat terminaalitiloja, kuinka kauan odotetaan, nollaako tilapäinen verkkovirhe ajastimen ja mitä tehdään containerin käynnistyessä uudelleen.

Agentti tekee nämä päätökset erityisen helposti väärin, koska se ei välttämättä tunne alustan koko tilakonetta. Alustan pitäisi vastata wait-semanticsistä.

Dockup tarjoaa kaksi hyödyllistä mallia:

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

deploy --wait odottaa eksplisiittisesti. push odottaa oletusarvoisesti pushin ja julkaisun käynnistämisen jälkeen; --no-wait poistaa odotuksen käytöstä. Molemmat palauttavat terminaalitilaa vastaavan exit-koodin.

Lokien seuraaminen noudattaa samaa ajatusta:

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

Virta päättyy, kun build saavuttaa onnistuneen tai epäonnistuneen tilan. Viimeinen NDJSON-objekti merkitsee arvon done:true, ja epäonnistunut build palauttaa nollasta poikkeavan exit-koodin. Kutsujan ei tarvitse toteuttaa toista polling-mekanismia.

Sovelluksen käytettävyyttä julkaisun jälkeen varten Dockupin uptime-komento palauttaa minuuttikohtaiset tarkistukset, keskimääräisen vastausajan ja p95-arvon:

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

Odotus ja monitorointi ovat eri asioita. --wait vastaa siihen, saavuttiko tämä julkaisu terminaalitilan; uptime kertoo, miten käynnissä oleva palvelu käyttäytyi ajan kuluessa.

Mitkä virhekoodit agentin pitäisi tuntea?

Vakaiden virheluokkien ansiosta agentti voi toteuttaa rajatun toimenpiteen tulkitsematta jokaista mahdollista viestiä. Dockup tarjoaa esimerkiksi seuraavat koodit:

Virhekoodi	Merkitys	Agentin turvallinen toiminta
not_logged_in	Käyttökelpoista tokenia ei ole	Pysähdy ja pyydä autentikointia
not_linked	push-komennolle ei ole .dockup-kohdetta	Selvitä kohde tai välitä se
no_target	Palvelua ei voitu tunnistaa	Suorita services --json
needs_confirm	Tuhoava toimenpide vaatii hyväksynnän	Kysy ihmiseltä
deploy_trigger_failed	Julkaisua ei voitu käynnistää	Raportoi API-virhe
deploy_failed	Build tai deploy päätyi epäonnistumiseen	Lue build-lokit
deploy_timeout	Suoritus jatkui odotusrajan jälkeen	Raportoi epävarmuus tai pidennä aikaa harkitusti

Virheviesti tarjoaa edelleen hyödyllistä kontekstia, mutta ensimmäistä haarautumista ohjaa koodi. Näin automaatio kestää selkeämmät sanamuodot tai lokalisoinnin.

Vahvistus on myös osa protokollaa. Tuhoavan komennon ei pitäisi jatkaa hiljaisesti vain siksi, että kutsuja on interaktiivinen. Dockup kieltäytyy tällaisista toiminnoista ilman --yes-valitsinta ja palauttaa arvon needs_confirm. Autonominen agentti näkee kysymyksen, ei ohitettavaa estettä.

Turvallisuusmallia käsitellään tarkemmin security best practices.

Mikä on tuotantovalmiin CLI:n vähimmäissopimus?

Tuotantovalmis AI-agentin CLI täyttää pienen mutta tiukan sopimuksen:

1. Jokaisella luku- ja kirjoitusoperaatiolla on koneellisesti luettava tuloste.
2. Virhe tuottaa nollasta poikkeavan prosessin exit-koodin.
3. Asynkroniset mutaatiot voivat odottaa dokumentoitua terminaalitilaa.
4. Salaisia arvoja ei koskaan palauteta lukukomennoilla.
5. Tuhoavat toiminnot vaativat eksplisiittisen vahvistuksen.
6. Virheillä on haarautumiseen soveltuvat vakaat koodit.
7. CLI-paketti ja agentin ohjeet pysyvät version suhteen linjassa.
8. Mutaatiot tallennetaan audit trailiin.

Dockupin skill muuttaa nämä säännöt oletustoiminnaksi Claude Codelle ja Codexille. Se ohjeistaa agenttia käyttämään JSONia, autentikoitumaan DOCKUP_TOKEN-muuttujalla, selvittämään täsmälliset kohteet, julkaisemaan --wait-valitsimella, suojaamaan tunnistetiedot ja pysähtymään arvon needs_confirm kohdalla.

Vertaa tätä mallia laajempiin käsitteisiin artikkelissa agent skills vs MCP. Skill tarjoaa toimintatiedon; CLI pysyy suoritettavana rajapintana, jonka exit-tila ja tuloste määrittävät totuuden.

Agentille suunnatun komennon testimatriisi

Ennen kuin annat infrastruktuurikomennon agentin käyttöön, testaa onnellisen polun lisäksi myös seuraavat tilanteet:

Testi	Odotettu toiminta
Kelvollinen pyyntö	JSON-tulos ja exit 0
Virheellinen token	Vakaa auth-koodi ja nollasta poikkeava exit-koodi
Tuntematon kohde	Vakaa kohdekoodi ilman mutaatiota
Pitkään kestävä deploy	Odottaa terminaalitilaan tai aikakatkaisuun asti
Epäonnistunut deploy	Nollasta poikkeava exit-koodi ja diagnosoitava deployment ID
Puuttuva tuhoavan toiminnon hyväksyntä	needs_confirm, ei poistoa
Salaisen arvon luku	Avaimen metadata näkyy, arvo on peitetty
Varoitus JSON-tulosteen aikana	Varoitus stderrissä, kelvollinen JSON stdoutissa

Tämä matriisi on arvokkaampi kuin viimeistelty progress spinner. Ihmisille tarkoitettu muotoilu voidaan lisätä päälle; determinististä koneellista sopimusta ei voi rakentaa jälkikäteen.

Dockupin CLI-dokumentaatio näyttää tämän mallin taustalla olevat konkreettiset komennot, kun taas AI-pohjainen kehitys selittää laajemman siirtymän manuaalisesta työkalujen käytöstä agenttiohjattuihin työnkulkuihin.

Käsittele observabilityä osana komentojen sopimusta

Agentille suunnatun mutaation pitäisi palauttaa tunnisteet, jotka mahdollistavat myöhemmän tutkinnan. Julkaisuvastauksessa tarvitaan kohde ja deployment ID; luodulla tietokannalla pitää olla pysyvä slug; volume snapshotilla tulee olla snapshot ID. Ilman näitä viitteitä agentti voi kuvata tapahtuman, mutta se ei voi luotettavasti tarkastella, yrittää uudelleen tai peruuttaa sitä.

Audit trail täydentää sopimuksen. Rakenteinen tuloste kuvaa yhtä kutsua, kun taas audit-tietueet yhdistävät useita kutsuja ajan kuluessa. Yhdessä ne auttavat operaattoreita selvittämään, toimiko agentti tarkoitetun resurssin parissa ja viittasiko myöhempi palautuskomento samaan tuotantotapahtumaan.

Pidä rajapinta tylsänä

Luotettavan AI-agentin CLI:n pitäisi toimia odotetusti onnistumisen, virheen, aikakatkaisun ja uudelleenyrityksen aikana.

Rajapinnan lopullinen testi

AI-agentin CLI:n on epäonnistuttava totuudenmukaisesti.

Vie työnkulku tuotantoon

Testaa sopimus ensin shellistä: varmista JSON-jäsennys, onnistunut exit, pakotettu virhe, aikakatkaisu ja estetty tuhoava toiminto ennen kuin annat agentille pääsyn tuotantoon.

npm install -g dockup-cli
dockup skill install

Ensimmäinen komento asentaa CLI:n. Toinen asentaa Claude Codelle ja Codexille tarkoitetun yhteensopivan Dockup skillin. Aloita ilmaiseksi osoitteessa app.dockup.ai.

UKK

Mikä tekee CLI:stä sopivan AI-agenteille?

Se tarvitsee rakenteisen tulosteen, oikeat exit-koodit, terminaalitilan odotuksen, vakaat virhekoodit, salaisten arvojen peittämisen sekä eksplisiittisen vahvistuksen tuhoaville toiminnoille.

Miksi JSON on agenteille parempi kuin ihmisille muotoiltu CLI-tuloste?

JSON tarjoaa vakaat kenttien nimet ja tyypit. Agentin ei tarvitse päätellä merkitystä väreistä, taulukoista, välimerkeistä tai muuttuvasta proosasta.

Miksi hyväksytty julkaisu-pyyntö ei tarkoita onnistumista?

Hyväksyntä osoittaa vain, että alusta asetti toiminnon jonoon. Myöhempi build, käynnistys, health gate ja liikenteen vaihto voivat edelleen epäonnistua.

Mikä on Dockup-julkaisun oletusarvoinen odotuksen aikakatkaisu?

Komennon dockup deploy --wait oletusaikakatkaisu on 900 sekuntia, ja sitä voi muuttaa dokumentoidulla --timeout-valitsimella.

Miten agentin pitäisi reagoida arvoon needs_confirm?

Sen pitäisi pysähtyä ja pyytää eksplisiittistä hyväksyntää. Koodi tarkoittaa, että pyydetty toiminto on tuhoava eikä sitä tarkoituksella suoritettu.