CLI-design for AI-agenter: JSON, exit-koder og venting

En CLI for AI-agenter er ikke bare et kommandolinjeverktøy for mennesker som tilfeldigvis kan kalles fra en modell. Det er en operasjonell protokoll. Agenten trenger deterministiske inndata, strukturerte utdata, meningsfulle exit-koder, stabile feilkategorier og en måte å vente på til asynkron infrastruktur når en endelig tilstand.

Uten denne kontrakten tvinges agenten til å utlede suksess fra formuleringer som «distribusjonen er startet». Denne slutningen er farlig fordi en forespørsel som er godtatt, senere kan mislykkes under bygging, helsesjekker, oppstart av containeren eller overføring av trafikk.

Hvorfor er det farlig å anta at en distribusjon var vellykket?

De fleste infrastrukturhandlinger er asynkrone. Et API kan godta en distribusjon og returnere en ID på millisekunder, mens selve byggingen tar flere minutter. Hvis en agent rapporterer suksess når forespørselen godtas, bygger alle senere trinn på en feilaktig forutsetning.

Se forskjellen:

Hendelse	Hva den beviser	Hva den ikke beviser
Forespørsel godtatt	Plattformen forsto forespørselen	At koden ble bygget
Bygging fullført	Et image eller artefakt ble opprettet	At appen startet
Helsesjekk godkjent	Den nye instansen svarte som forventet	At forretningsflytene fungerer
Trafikk byttet	Versjonen ble aktiv	At den forblir frisk
Oppetidsobservasjon	Tjenesten fortsatt er tilgjengelig	At alle funksjoner er korrekte

Et menneske kan se forskjellen i et dashboard. En agent som opererer gjennom tekst, trenger at forskjellen er kodet inn i grensesnittet.

Dockups kommandokontrakt skiller mellom kølegging og fullføring. En distribusjon uten --wait returnerer umiddelbart med waited:false; en distribusjon med --wait blokkerer til suksess, feil eller tidsavbrudd:

dockup deploy production/api --wait --json

Standardtidsavbruddet er 900 sekunder. Kommandoen avsluttes med 0 først når en vellykket sluttstatus er nådd. Den avsluttes med en verdi ulik null og deploy_failed eller deploy_timeout når resultatet ikke er suksess.

Hva gir en strukturert JSON-CLI en AI-agent?

Strukturert JSON erstatter tolkning av fritekst med navngitte felt. Agenten kan finne status, deploymentId, target eller code direkte, i stedet for å være avhengig av tegnsetting, farger, 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 feil bruker samme transportformat:

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

Den viktige designregelen er at JSON skrives til stdout, mens advarsler som ikke må ødelegge parsingen, sendes til stderr. Logger i følge-modus bruker NDJSON – ett JSON-objekt per linje – slik at en kallende prosess kan behandle en strøm trinnvis uten å vente på én stor array.

Dockup bruker --json på tvers av hele kommandoflaten. Med 135 kommandoer ville det vært skjørt å kreve at en agent husker flagg fra gang til gang. CLI-referansen og den medfølgende skillen gir versjonstilpassede kommandoinstruksjoner som agenten skal følge.

Den viktige egenskapen er ikke intelligent oppdagelse. Det er at agenten mottar oppdatert, strukturert driftsveiledning og ikke finner på et flagg basert på en gammel prompt.

Hvordan bør reelle exit-koder styre distribusjonsautomatisering?

Exit-koden fra operativsystemet er det mest portable suksesssignalet som er tilgjengelig for shell-skript, CI-kjørere og kodeagenter. Exit 0 betyr at kommandoen oppnådde det definerte resultatet. En verdi ulik null betyr at den kallende prosessen må velge gjenoppretting, eskalering eller avslutning.

Dette shell-utdraget er med vilje kjedelig:

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 leter ikke etter ordet «success» i stdout. Det antar ikke at et HTTP 202-svar betyr at produksjonen er klar. Det overlater definisjonen av suksess til CLI-en og viderefører feilen til den overordnede prosessen.

Reelle exit-koder er like viktige for engangskommandoer inne i en container. Dockups PRO-kommando exec returnerer stdout, stderr og den faktiske exit-koden til kommandoen:

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

En agent kan dermed skille mellom en fullført migrering og en kommando som bare ble startet. Dette er et grunnleggende prinsipp i produksjonsvernregler for AI-agenter.

Hvordan erstatter venting på sluttstatus sårbar polling?

Håndskrevne polling-løkker introduserer skjulte policyvalg: hvor ofte det skal polles, hvilke tilstander som er endelige, hvor lenge man skal vente, om en forbigående nettverksfeil skal tilbakestille tidsuret, og hva som skal skje når en container starter på nytt.

En agent gjør særlig lett feil i disse valgene fordi den kanskje ikke kjenner hele tilstandsmaskinen til plattformen. Plattformen bør eie ventemekanikken.

Dockup tilbyr to nyttige mønstre:

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

deploy --wait venter eksplisitt. push venter som standard etter pushing og utløsning av versjonen; --no-wait deaktiverer dette. Begge returnerer en exit-kode som gjenspeiler sluttresultatet.

Følging av logger følger samme idé:

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

Strømmen avsluttes når byggingen når suksess eller feil. Et siste NDJSON-objekt markerer done:true, og en mislykket bygging avsluttes med en verdi ulik null. Den kallende prosessen trenger ikke en ny polling-implementasjon.

For å kontrollere tilgjengeligheten til applikasjonen etter en distribusjon returnerer Dockups uptime-kommando kontroller på minuttnivå, gjennomsnittlig svartid og p95:

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

Venting og overvåking er separate konsepter. --wait svarer på om denne distribusjonen nådde et sluttresultat; uptime svarer på hvordan den kjørende tjenesten oppførte seg over tid.

Hvilke feilkoder bør en agent forstå?

Stabile feilkategorier lar en agent utføre en avgrenset handling uten å tolke hver eneste melding. Dockup eksponerer koder som:

Feilkode	Betydning	Trygg respons fra agenten
not_logged_in	Ingen brukbar token	Stopp og be om autentisering
not_linked	Ingen .dockup-mål for push	Finn målet eller oppgi det
no_target	Tjenesten kunne ikke identifiseres	Kjør services --json
needs_confirm	Destruktiv handling mangler godkjenning	Spør et menneske
deploy_trigger_failed	Distribusjonen kunne ikke startes	Rapporter API-feilen
deploy_failed	Byggingen eller distribusjonen mislyktes	Les byggelogger
deploy_timeout	Kjører fortsatt etter ventetidsgrensen	Rapporter usikkerhet eller utvid ventetiden bevisst

Feilmeldingen er fortsatt nyttig som kontekst, men koden styrer den første forgreningen. Dermed tåler automatiseringen tydeligere formuleringer eller lokalisering.

Bekreftelse er også en del av protokollen. En destruktiv kommando skal ikke fortsette i stillhet bare fordi den kallende prosessen ikke er interaktiv. Dockup avviser slike handlinger uten --yes og returnerer needs_confirm. En autonom agent ser et spørsmål, ikke en hindring som skal omgås.

Sikkerhetsmodellen utforskes nærmere i beste praksis for sikkerhet.

Hva er minimumskontrakten for en produksjonsklar CLI?

En produksjonsklar CLI for AI-agenter bør oppfylle en liten, men streng kontrakt:

1. Alle lese- og skriveoperasjoner har maskinlesbare utdata.
2. Feil gir en prosess-exit ulik null.
3. Asynkrone endringer kan vente på en dokumentert sluttstatus.
4. Hemmelige verdier returneres aldri av lese-kommandoer.
5. Destruktive handlinger krever eksplisitt bekreftelse.
6. Feil har stabile koder som kan brukes i forgreninger.
7. CLI-pakken og agentinstruksjonene holder seg på linje med hverandre versjonsmessig.
8. Endringer registreres i en revisjonssporing.

Dockups skill gjør disse reglene til standardatferd for Claude Code og Codex. Den instruerer agenten til å bruke JSON, autentisere med DOCKUP_TOKEN, finne nøyaktige mål, distribuere med --wait, beskytte legitimasjon og stoppe ved needs_confirm.

Sammenlign denne modellen med de bredere konseptene i agent skills kontra MCP. En skill tilfører driftskunnskap; CLI-en forblir det kjørbare grensesnittet der exit-status og utdata definerer sannheten.

En testmatrise for en agentvendt kommando

Før du eksponerer en infrastrukturkommando for en agent, bør du teste mer enn den lykkelige veien:

Test	Forventet atferd
Gyldig forespørsel	JSON-resultat og exit 0
Ugyldig token	Stabil autentiseringskode og exit ulik null
Ukjent mål	Stabil målkode og ingen endring
Langvarig distribusjon	Venter til sluttstatus eller tidsavbrudd
Mislykket distribusjon	Exit ulik null samt en distribusjons-ID som kan brukes til feilsøking
Manglende destruktiv godkjenning	needs_confirm, ingen sletting
Lesing av hemmelighet	Nøkkelmetadata synlig, verdi maskert
Advarsel under JSON-utdata	Advarsel på stderr, gyldig JSON på stdout

Denne matrisen er mer verdifull enn en polert fremdriftsindikator. Menneskevennlig formatering kan legges oppå; en deterministisk maskinkontrakt kan ikke rekonstrueres i etterkant.

Dockups CLI-dokumentasjon viser de konkrete kommandoene bak denne modellen, mens AI-drevet utvikling forklarer den større overgangen fra manuell verktøybruk til agentstyrte arbeidsflyter.

Behandle observerbarhet som en del av kommandokontrakten

En endring utført på vegne av en agent bør returnere identifikatorer som gjør senere undersøkelser mulig. Et distribusjonssvar trenger målet og distribusjons-ID-en; en opprettet database trenger en stabil slug; et volumøyeblikksbilde trenger snapshot-ID-en sin. Uten disse referansene kan agenten beskrive en hendelse, men ikke pålitelig inspisere, prøve på nytt eller reversere den.

Revisjonssporet fullfører kontrakten. Strukturert utdata forklarer én kjøring, mens revisjonsoppføringer knytter flere kjøringer sammen over tid. Sammen gjør de det mulig for operatører å svare på om agenten handlet på riktig ressurs, og om en senere gjenopprettingskommando refererte til den samme produksjonshendelsen.

Hold grensesnittet kjedelig

En pålitelig CLI for AI-agenter bør være forutsigbar ved suksess, feil, tidsavbrudd og nye forsøk.

Endelig grensesnitttest

CLI-en for AI-agenter må feile på en sannferdig måte.

Sett arbeidsflyten i produksjon

Test kontrakten fra et shell først: verifiser JSON-parsing, en vellykket exit, en fremtvunget feil, et tidsavbrudd og en blokkert destruktiv handling før du gir agenten tilgang til produksjon.

npm install -g dockup-cli
dockup skill install

Den første kommandoen installerer CLI-en. Den andre installerer den tilhørende Dockup-skillen for Claude Code og Codex. Kom i gang gratis på app.dockup.ai.

Vanlige spørsmål

Hva gjør en CLI egnet for AI-agenter?

Den trenger strukturerte utdata, reelle exit-koder, venting på sluttstatus, stabile feilkoder, maskering av hemmeligheter og eksplisitt bekreftelse for destruktive handlinger.

Hvorfor er JSON bedre enn menneskeformatert CLI-utdata for agenter?

JSON gir stabile feltnavn og typer. Agenten trenger ikke å utlede betydningen fra farger, tabeller, tegnsetting eller skiftende formuleringer.

Hvorfor er ikke en godtatt distribusjonsforespørsel det samme som suksess?

Godkjenning beviser bare at plattformen la operasjonen i kø. Den senere byggingen, oppstarten, helsesjekken og overføringen av trafikk kan fortsatt mislykkes.

Hva er standard ventetidsavbrudd for Dockup-distribusjoner?

Standardtidsavbruddet for dockup deploy --wait er 900 sekunder, og det kan endres med det dokumenterte --timeout-alternativet.

Hvordan bør en agent reagere på needs_confirm?

Den bør stoppe og be om eksplisitt godkjenning. Koden betyr at den forespurte handlingen er destruktiv og med hensikt ikke ble utført.