Design af CLI til AI-agenter: JSON, exitkoder og ventetid

En CLI til AI-agenter er ikke bare et command-line-værktøj til mennesker, som tilfældigvis kan kaldes fra en model. Det er en operationel protokol. Agenten har brug for deterministiske input, strukturerede outputs, meningsfulde exitkoder, stabile fejlkategorier og en måde at vente på, at asynkron infrastruktur når en endelig tilstand.

Uden denne kontrakt tvinges en agent til at udlede succes fra formuleringer som “deployment startet”. Den slutning er farlig, fordi en accepteret request senere kan fejle under build, health checks, opstart af containeren eller omlægning af trafik.

Hvorfor er gættet deploysucces farlig?

De fleste infrastrukturhandlinger er asynkrone. En API kan acceptere et deployment og returnere et ID på millisekunder, mens det faktiske build tager flere minutter. Hvis en agent rapporterer succes ved acceptgrænsen, bygger alle efterfølgende trin på en falsk forudsætning.

Overvej forskellen:

Hændelse	Hvad den beviser	Hvad den ikke beviser
Request accepteret	Platformen forstod requesten	At koden blev bygget
Build gennemført	Et image eller artefakt blev oprettet	At appen startede
Health gate bestået	Den nye instans svarede som krævet	At forretningsflows fungerer
Trafik omlagt	Releasen blev aktiv	At den forbliver sund
Uptime-observation	Servicen kan fortsat nås	At alle funktioner er korrekte

Et menneske kan se forskellen i et dashboard. En agent, der arbejder via tekst, har brug for, at forskellen er indkodet i interfacet.

Dockups kommandokontrakt adskiller køsætning fra færdiggørelse. Et deploy uden --wait returnerer med det samme med waited:false; et deploy med --wait blokerer, indtil resultatet er succes, fejl eller timeout:

dockup deploy production/api --wait --json

Standard-timeout er 900 sekunder. Kommandoen afslutter med 0, men kun efter en vellykket terminaltilstand. Den afslutter med en non-zero-kode og deploy_failed eller deploy_timeout, når resultatet ikke er succes.

Hvad giver en struktureret JSON-CLI en AI-agent?

Struktureret JSON erstatter fortolkning af prosa med navngivne felter. Agenten kan finde status, deploymentId, target eller code direkte i stedet for at være afhængig af tegnsætning, farver, kolonnebredde eller formuleringer.

Et vellykket resultat kan behandles som data:

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

En fejl bruger samme transportformat:

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

Den vigtige designregel er, at JSON skrives til stdout, mens advarsler, der ikke må ødelægge parsing, sendes til stderr. Logs i follow-mode bruger NDJSON – ét JSON-objekt pr. linje – så en caller kan behandle en stream trinvist uden at vente på ét stort array.

Dockup anvender --json på tværs af hele kommandofladen. Med 135 kommandoer ville det være skrøbeligt at kræve, at en agent husker flags fra hukommelsen. CLI-referencen og den pakkede skill indeholder de versionsafstemte kommandoinstruktioner, agenten skal følge.

Den vigtige egenskab er ikke avanceret discovery. Det afgørende er, at agenten modtager aktuelle, strukturerede driftsinstruktioner og ikke opfinder et flag ud fra en gammel prompt.

Hvordan bør reelle exitkoder styre deployautomatisering?

Operativsystemets exitkode er det mest portable succeskriterium, der findes til shell-scripts, CI-runners og coding agents. Exit 0 betyder, at kommandoen opnåede det definerede resultat. En non-zero-kode betyder, at caller’en skal vælge recovery, eskalering eller afslutning.

Dette shell-udsnit er med vilje kedeligt:

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

Det leder ikke efter ordet “success” i stdout. Det antager ikke, at et HTTP 202-svar betyder, at produktionen er klar. Det overlader definitionen af succes til CLI’en og viderefører fejlen til den overordnede proces.

Reelle exitkoder er lige så vigtige for one-shot-kommandoer i en container. Dockups PRO-kommando exec returnerer stdout, stderr og den faktiske exitkode for kommandoen:

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

En agent kan derfor skelne mellem en gennemført migration og en kommando, der blot blev startet. Det er et grundlæggende princip i produktionsguardrails til AI-agenter.

Hvordan erstatter ventetid på terminaltilstand skrøbelig polling?

Håndskrevne polling-loops introducerer skjulte politikbeslutninger: hvor ofte der skal poll’es, hvilke tilstande der er terminale, hvor længe der skal ventes, om en midlertidig netværksfejl skal nulstille timeren, og hvad der skal ske, når en container genstarter.

En agent vil især kunne træffe de beslutninger forkert, fordi den måske ikke kender platformens komplette state machine. Platformen bør selv eje ventesemantikken.

Dockup tilbyder to nyttige mønstre:

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

deploy --wait venter eksplicit. push venter som standard efter push og aktivering af releasen; --no-wait fravælger ventetiden. Begge returnerer en exitkode, der afspejler det terminale resultat.

Log-following følger samme idé:

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

Streamen slutter, når buildet når succes eller fejl. Et afsluttende NDJSON-objekt markerer done:true, og et fejlet build afsluttes med en non-zero-kode. Caller’en behøver ikke en ekstra polling-implementering.

Hvis applikationens tilgængelighed efter deployment skal kontrolleres, returnerer Dockups uptime-kommando checks på minutniveau, gennemsnitlig svartid og p95:

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

Ventetid og monitorering er to forskellige begreber. --wait besvarer, om dette deployment nåede et terminalt resultat; uptime viser, hvordan den kørende service opførte sig over tid.

Hvilke fejlkoder bør en agent forstå?

Stabile fejlkategorier gør det muligt for en agent at udføre en afgrænset handling uden at fortolke enhver mulig besked. Dockup eksponerer blandt andet disse koder:

Fejlkode	Betydning	Sikkert agentsvar
not_logged_in	Intet brugbart token	Stop og bed om authentication
not_linked	Intet .dockup-target til push	Find targetet, eller angiv det
no_target	Servicen kunne ikke identificeres	Kør services --json
needs_confirm	Destruktiv handling mangler godkendelse	Spørg et menneske
deploy_trigger_failed	Deployment kunne ikke startes	Rapportér API-fejlen
deploy_failed	Build eller deploy endte med fejl	Læs build-logs
deploy_timeout	Kører stadig efter ventetidsgrænsen	Rapportér usikkerhed, eller udvid ventetiden bevidst

Fejlbeskeden er stadig nyttig som kontekst, men koden styrer den første branch. Det gør automatiseringen robust over for tydeligere formuleringer eller lokalisering.

Bekræftelse er også en del af protokollen. En destruktiv kommando må ikke fortsætte stiltiende, blot fordi caller’en ikke er interaktiv. Dockup afviser sådanne handlinger uden --yes og returnerer needs_confirm. En autonom agent ser et spørgsmål, ikke en barriere, der skal omgås.

Sikkerhedsmodellen udforskes yderligere i bedste praksis for sikkerhed.

Hvad er minimumskontrakten for en produktionsklar CLI?

En produktionsklar CLI til AI-agenter bør opfylde en lille, men streng kontrakt:

1. Alle read- og write-operationer har maskinlæsbare outputs.
2. Fejl giver en non-zero-procesexit.
3. Asynkrone mutationer kan vente på en dokumenteret terminaltilstand.
4. Hemmelige værdier returneres aldrig af read-kommandoer.
5. Destruktive handlinger kræver eksplicit bekræftelse.
6. Fejl har stabile koder, der kan bruges til branching.
7. CLI-pakken og agentinstruktionerne forbliver versionsafstemte.
8. Mutationer registreres i et audit trail.

Dockups skill omsætter disse regler til standardadfærd for Claude Code og Codex. Den instruerer agenten i at bruge JSON, autentificere med DOCKUP_TOKEN, finde præcise targets, deploye med --wait, beskytte credentials og stoppe ved needs_confirm.

Sammenlign denne model med de bredere begreber i agent skills vs MCP. En skill leverer driftsmæssig viden; CLI’en er stadig det eksekverbare interface, hvis exitstatus og output definerer sandheden.

En testmatrix for en agentvendt kommando

Før en infrastrukturkommando eksponeres for en agent, skal du teste mere end happy path:

Test	Forventet adfærd
Gyldig request	JSON-resultat og exit 0
Ugyldigt token	Stabil auth-kode og non-zero-exit
Ukendt target	Stabil target-kode og ingen mutation
Langvarigt deploy	Venter på terminaltilstand eller timeout
Fejlet deploy	Non-zero-exit samt et deployment-ID, der kan diagnosticeres
Manglende destruktiv godkendelse	needs_confirm, ingen sletning
Læsning af secret	Nøglets metadata er synlig, værdien maskeret
Advarsel under JSON-output	Advarsel på stderr, gyldig JSON på stdout

Denne matrix er mere værdifuld end en poleret progress-spinner. Menneskevenlig formatering kan lægges ovenpå; en deterministisk maskinkontrakt kan ikke genskabes bagefter.

Dockup CLI-dokumentationen viser de konkrete kommandoer bag denne model, mens AI-drevet udvikling forklarer det større skifte fra manuel brug af værktøjer til agentstyrede workflows.

Betragt observability som en del af kommandokontrakten

En mutation, der er rettet mod en agent, bør returnere identifikatorer, som gør senere undersøgelse mulig. Et deployment-svar skal indeholde target og deployment-ID; en oprettet database skal have en stabil slug; et volume-snapshot skal have sit snapshot-ID. Uden disse referencer kan agenten beskrive en hændelse, men kan ikke pålideligt inspicere, prøve igen eller rulle den tilbage.

Audit trail’et fuldender kontrakten. Struktureret output forklarer én invocation, mens audit records forbinder flere invocationer over tid. Tilsammen gør de det muligt for operatører at besvare, om agenten handlede på den tilsigtede resource, og om en senere recovery-kommando refererede til den samme produktionhændelse.

Hold interfacet kedeligt

En pålidelig CLI til AI-agenter bør være forudsigelig ved succes, fejl, timeout og retry.

Endelig interfacetest

CLI’en til AI-agenter skal fejle sandfærdigt.

Sæt workflowet i produktion

Test først kontrakten fra en shell: kontrollér JSON-parsing, en vellykket exit, en fremtvunget fejl, en timeout og en blokeret destruktiv handling, før du overlader produktionsadgang til en agent.

npm install -g dockup-cli
dockup skill install

Den første kommando installerer CLI’en. Den anden installerer den matchende Dockup-skill til Claude Code og Codex. Kom gratis i gang på app.dockup.ai.

Ofte stillede spørgsmål

Hvad gør en CLI egnet til AI-agenter?

Den skal have struktureret output, reelle exitkoder, ventetid på terminaltilstande, stabile fejlkoder, maskering af secrets og eksplicit bekræftelse af destruktive handlinger.

Hvorfor er JSON bedre end menneskeformateret CLI-output til agenter?

JSON giver stabile feltnavne og typer. Agenten behøver ikke udlede betydningen fra farver, tabeller, tegnsætning eller skiftende prosa.

Hvorfor er en accepteret deployment-request ikke det samme som succes?

Accepten beviser kun, at platformen satte operationen i kø. Det efterfølgende build, opstart, health gate og trafikskift kan stadig fejle.

Hvad er standardventetiden for Dockup-deployments?

Standard-timeout for dockup deploy --wait er 900 sekunder, og den kan ændres med den dokumenterede --timeout-option.

Hvordan bør en agent reagere på needs_confirm?

Den bør stoppe og bede om eksplicit godkendelse. Koden betyder, at den ønskede handling er destruktiv og med vilje ikke blev udført.