Ontwerp van een AI-agent-CLI: JSON, exitcodes en wachten

Een AI-agent-CLI is niet simpelweg een command-linetool voor mensen die toevallig vanuit een model kan worden aangeroepen. Het is een operationeel protocol. De agent heeft deterministische invoer, gestructureerde uitvoer, betekenisvolle exitcodes, stabiele foutcategorieën en een manier nodig om te wachten totdat asynchrone infrastructuur een definitieve status bereikt.

Zonder dat contract moet een agent succes afleiden uit tekst zoals ‘deployment gestart’. Dat is gevaarlijk, omdat een geaccepteerd verzoek later kan mislukken tijdens de build, health checks, het starten van de container of het omschakelen van verkeer.

Waarom is gegokt deploymentsucces gevaarlijk?

De meeste infrastructuuroperaties zijn asynchroon. Een API kan een deployment accepteren en binnen milliseconden een ID retourneren, terwijl de daadwerkelijke build enkele minuten duurt. Als een agent succes rapporteert zodra het verzoek is geaccepteerd, is elke volgende stap gebaseerd op een onjuist uitgangspunt.

Kijk naar het verschil:

Gebeurtenis	Wat dit bewijst	Wat dit niet bewijst
Verzoek geaccepteerd	Het platform heeft het verzoek begrepen	Dat de code is gebouwd
Build voltooid	Er is een image of artifact gemaakt	Dat de app is gestart
Health gate geslaagd	De nieuwe instance reageerde zoals vereist	Dat bedrijfsprocessen werken
Verkeer omgeschakeld	De release actief is geworden	Dat deze gezond blijft
Uptime-observatie	De service bereikbaar blijft	Dat elke feature correct werkt

Een mens ziet het verschil mogelijk in een dashboard. Een agent die via tekst werkt, heeft dit verschil in de interface nodig.

Het commandocontract van Dockup maakt onderscheid tussen in de wachtrij plaatsen en voltooien. Een deploy zonder --wait retourneert direct met waited:false; een deploy met --wait blokkeert totdat de status geslaagd, mislukt of verlopen is:

dockup deploy production/api --wait --json

De standaardtimeout is 900 seconden. De opdracht eindigt met 0 zodra een succesvolle terminale status is bereikt. Bij een ander resultaat dan succes eindigt de opdracht met een non-zero exitcode en deploy_failed of deploy_timeout.

Wat levert een gestructureerde JSON-CLI een AI-agent op?

Gestructureerde JSON vervangt het interpreteren van proza door benoemde velden. De agent kan status, deploymentId, target of code rechtstreeks vinden, zonder afhankelijk te zijn van leestekens, kleur, kolombreedte of formulering.

Een succesvol resultaat kan als data worden verwerkt:

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

Een fout gebruikt dezelfde transportstructuur:

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

De belangrijkste ontwerpregel is dat JSON naar stdout wordt geschreven, terwijl waarschuwingen die de parsing niet mogen verstoren naar stderr gaan. Logs in follow-modus gebruiken NDJSON—één JSON-object per regel—zodat een aanroeper een stream incrementeel kan verwerken zonder te wachten op één enorme array.

Dockup gebruikt --json voor alle commando’s. Met 135 commando’s zou het kwetsbaar zijn om van een agent te verlangen dat deze flags uit het hoofd afleidt. De CLI-referentie en de meegeleverde skill bieden de command-instructies die bij de versie passen en die de agent moet volgen.

De belangrijke ontwerpeigenschap is niet slimme discovery. Het gaat erom dat de agent actuele, gestructureerde operationele instructies ontvangt en geen flag uit een oude prompt verzint.

Hoe sturen echte exitcodes deploymentautomatisering aan?

De exitcode van het besturingssysteem is het meest draagbare succes-signaal voor shellscripts, CI-runners en coding agents. Exitcode 0 betekent dat het commando het gedefinieerde resultaat heeft bereikt. Een non-zero code betekent dat de aanroeper moet overschakelen naar herstel, escalatie of beëindiging.

Dit shellfragment is bewust saai:

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

Het zoekt niet in stdout naar het woord ‘success’. Het gaat er niet van uit dat een HTTP 202-response betekent dat productie klaar is. Het laat de CLI bepalen wat succes betekent en geeft fouten door aan het bovenliggende proces.

Echte exitcodes zijn ook belangrijk voor eenmalige commando’s binnen een container. Dockups PRO-commando exec retourneert stdout, stderr en de daadwerkelijke exitcode van het commando:

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

Een agent kan zo onderscheid maken tussen een voltooide migratie en een commando dat alleen is gestart. Dit is een fundamenteel principe van productie-guardrails voor AI-agents.

Hoe vervangt wachten op een terminale status kwetsbaar pollen?

Zelfgeschreven polling-loops introduceren verborgen beleidskeuzes: hoe vaak je pollt, welke statussen terminaal zijn, hoe lang je wacht, of een tijdelijke netwerkfout de timer moet resetten en wat je doet wanneer een container opnieuw wordt gestart.

Een agent maakt deze keuzes extra snel verkeerd, omdat deze mogelijk niet bekend is met de volledige state machine van het platform. Het platform hoort de wachtsemantiek te beheren.

Dockup biedt twee nuttige patronen:

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

deploy --wait wacht expliciet. push wacht standaard nadat de push en het starten van de release zijn uitgevoerd; --no-wait schakelt dit uit. Beide retourneren een exitcode die het terminale resultaat weerspiegelt.

Het volgen van logs volgt hetzelfde principe:

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

De stream eindigt wanneer de build de status geslaagd of mislukt bereikt. Een laatste NDJSON-object markeert done:true en bij een mislukte build eindigt het commando met een non-zero exitcode. De aanroeper heeft geen tweede polling-implementatie nodig.

Voor de beschikbaarheid van de applicatie na een deployment retourneert de uptime-opdracht van Dockup controles per minuut, de gemiddelde responstijd en p95:

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

Wachten en monitoring zijn verschillende concepten. --wait beantwoordt de vraag of deze deployment een terminale status heeft bereikt; uptime laat zien hoe de draaiende service zich in de loop van de tijd gedraagt.

Welke foutcodes moet een agent begrijpen?

Met stabiele foutcategorieën kan een agent een afgebakende actie uitvoeren zonder elk mogelijk bericht te interpreteren. Dockup biedt onder andere deze codes:

Foutcode	Betekenis	Veilige reactie van de agent
not_logged_in	Geen bruikbaar token	Stoppen en om authenticatie vragen
not_linked	Geen .dockup-target voor push	De target oplossen of meegeven
no_target	Service kon niet worden geïdentificeerd	services --json uitvoeren
needs_confirm	Voor de destructieve actie ontbreekt goedkeuring	Een mens vragen
deploy_trigger_failed	Deployment kon niet worden gestart	De API-fout rapporteren
deploy_failed	Build of deployment is mislukt	Buildlogs lezen
deploy_timeout	Nog actief nadat de wachttijd is verstreken	Onzekerheid rapporteren of bewust langer wachten

De foutmelding blijft nuttige context bieden, maar de code bepaalt de eerste vertakking. Daardoor blijft automatisering bestand tegen duidelijkere formuleringen of lokalisatie.

Bevestiging maakt ook deel uit van het protocol. Een destructief commando mag niet stilzwijgend doorgaan omdat de aanroeper niet-interactief is. Dockup weigert zulke acties zonder --yes en retourneert needs_confirm. Een autonome agent ziet dan een vraag, geen blokkade die moet worden omzeild.

Het veiligheidsmodel wordt verder uitgewerkt in best practices voor security.

Wat is het minimale contract voor een production-ready CLI?

Een production-ready AI-agent-CLI hoort aan een klein maar strikt contract te voldoen:

1. Elke read- en write-operatie heeft machineleesbare uitvoer.
2. Een fout resulteert in een non-zero process exit.
3. Asynchrone mutaties kunnen wachten op een gedocumenteerde terminale status.
4. Geheimen worden nooit door read-commando’s geretourneerd.
5. Voor destructieve acties is expliciete bevestiging vereist.
6. Fouten hebben stabiele codes waarop kan worden vertakt.
7. Het CLI-package en de agentinstructies blijven op dezelfde versie afgestemd.
8. Mutaties worden vastgelegd in een audit trail.

De skill van Dockup maakt van deze regels standaardgedrag voor Claude Code en Codex. De skill instrueert de agent om JSON te gebruiken, te authenticeren met DOCKUP_TOKEN, exacte targets te vinden, deployments met --wait uit te voeren, credentials te beschermen en te stoppen bij needs_confirm.

Vergelijk dit model met de bredere concepten in agent skills versus MCP. Een skill levert operationele kennis; de CLI blijft de uitvoerbare interface waarvan de exitstatus en uitvoer de waarheid bepalen.

Een testmatrix voor een command dat door een agent wordt aangeroepen

Test meer dan alleen het happy path voordat je een infrastructuurcommando aan een agent beschikbaar stelt:

Test	Verwacht gedrag
Geldig verzoek	JSON-resultaat en exitcode 0
Ongeldig token	Stabiele authenticatiecode en non-zero exitcode
Onbekende target	Stabiele targetcode en geen mutatie
Langlopende deployment	Wacht totdat een terminale status of timeout is bereikt
Mislukte deployment	Non-zero exitcode plus een te diagnosticeren deployment-ID
Ontbrekende goedkeuring voor destructieve actie	needs_confirm, geen verwijdering
Geheim uitlezen	Key-metadata zichtbaar, waarde gemaskeerd
Waarschuwing tijdens JSON-uitvoer	Waarschuwing op stderr, geldige JSON op stdout

Deze matrix is waardevoller dan een fraai vormgegeven progress spinner. Mensgerichte formatting kan erbovenop worden gezet; een deterministisch machinecontract kun je achteraf niet reconstrueren.

De Dockup CLI-documentatie toont de concrete commando’s achter dit model, terwijl AI-ondersteunde development de bredere verschuiving van handmatig toolgebruik naar door agents aangestuurde workflows uitlegt.

Behandel observability als onderdeel van het commandocontract

Een mutatie die door een agent wordt aangeroepen, moet identifiers retourneren waarmee later onderzoek mogelijk is. Een deploymentresponse heeft de target en deployment-ID nodig; een aangemaakte database heeft een stabiele slug nodig; een volume-snapshot heeft zijn snapshot-ID nodig. Zonder deze verwijzingen kan de agent een gebeurtenis beschrijven, maar niet betrouwbaar inspecteren, opnieuw proberen of ongedaan maken.

De audit trail maakt het contract compleet. Gestructureerde uitvoer beschrijft één aanroep, terwijl auditrecords meerdere aanroepen in de tijd met elkaar verbinden. Samen maken ze het mogelijk om te bepalen of de agent de bedoelde resource heeft gebruikt en of een later herstelcommando naar hetzelfde productie-event verwees.

Houd de interface saai

Een betrouwbare AI-agent-CLI hoort voorspelbaar te zijn bij succes, fouten, timeouts en retries.

Laatste interfacetest

De AI-agent-CLI moet waarheidsgetrouw falen.

Breng de workflow naar productie

Test het contract eerst vanuit een shell: controleer JSON-parsing, een succesvolle exit, een geforceerde fout, een timeout en een geblokkeerde destructieve operatie voordat je productie-toegang delegeert.

npm install -g dockup-cli
dockup skill install

Het eerste commando installeert de CLI. Het tweede installeert de bijbehorende Dockup-skill voor Claude Code en Codex. Begin gratis via app.dockup.ai.

FAQ

Wat maakt een CLI geschikt voor AI-agents?

De CLI heeft gestructureerde uitvoer, echte exitcodes, wachten op een terminale status, stabiele foutcodes, het maskeren van geheimen en expliciete bevestiging voor destructieve acties nodig.

Waarom is JSON beter dan mensgerichte CLI-uitvoer voor agents?

JSON biedt stabiele veldnamen en datatypen. De agent hoeft de betekenis niet af te leiden uit kleuren, tabellen, leestekens of veranderende tekst.

Waarom is een geaccepteerd deploymentverzoek geen succes?

Acceptatie bewijst alleen dat het platform de operatie in de wachtrij heeft geplaatst. De daaropvolgende build, het starten, de health gate en het omschakelen van verkeer kunnen nog steeds mislukken.

Wat is de standaard wachttimeout voor Dockup-deployments?

De standaardtimeout voor dockup deploy --wait is 900 seconden. Deze kan worden gewijzigd met de gedocumenteerde --timeout-optie.

Hoe moet een agent reageren op needs_confirm?

De agent moet stoppen en om expliciete goedkeuring vragen. De code betekent dat de gevraagde actie destructief is en bewust niet is uitgevoerd.