Design av CLI för AI-agenter: JSON, exitkoder och väntan

Ett CLI för AI-agenter är inte bara ett kommandoradsverktyg för människor som råkar kunna anropas från en modell. Det är ett operativt protokoll. Agenten behöver deterministiska indata, strukturerade utdata, meningsfulla exitkoder, stabila felkategorier och ett sätt att vänta tills asynkron infrastruktur når ett slutgiltigt tillstånd.

Utan det avtalet tvingas en agent dra slutsatser om framgång från formuleringar som ”deployment har startat”. Det är riskabelt, eftersom en accepterad begäran senare kan misslyckas under build, hälsokontroller, containerstart eller trafikväxling.

Varför är det farligt att gissa att en deployment lyckades?

De flesta infrastrukturåtgärder är asynkrona. Ett API kan acceptera en deployment och returnera ett ID på millisekunder, medan själva builden tar flera minuter. Om en agent rapporterar framgång när begäran accepteras bygger varje senare steg på en felaktig utgångspunkt.

Tänk på skillnaden:

Händelse	Vad den bevisar	Vad den inte bevisar
Begäran accepterad	Plattformen förstod begäran	Att koden byggdes
Build slutförd	En image eller artefakt skapades	Att appen startade
Hälsokontroll godkänd	Den nya instansen svarade enligt kraven	Att affärsflöden fungerar
Trafik växlad	Release-versionen blev aktiv	Att den förblir frisk
Tillgänglighetsobservation	Tjänsten förblir nåbar	Att alla funktioner fungerar

En människa kan se skillnaden i en dashboard. En agent som arbetar via text behöver få den kodad i gränssnittet.

Dockups kommandokontrakt skiljer köläggning från slutförande. En deploy utan --wait returnerar omedelbart med waited:false; en deploy med --wait blockerar tills den lyckas, misslyckas eller når timeout:

dockup deploy production/api --wait --json

Standard-timeouten är 900 sekunder. Kommandot avslutas med 0 först efter ett lyckat slutgiltigt tillstånd. Det avslutas med en kod som inte är noll och deploy_failed eller deploy_timeout när resultatet inte är en framgång.

Vad ger ett strukturerat JSON-CLI en AI-agent?

Strukturerad JSON ersätter tolkning av löptext med namngivna fält. Agenten kan hitta status, deploymentId, target eller code direkt i stället för att vara beroende av interpunktion, färger, kolumnbredd eller formuleringar.

Ett lyckat resultat kan konsumeras som data:

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

Ett fel använder samma transportformat:

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

Den viktiga designregeln är att JSON skrivs till stdout, medan varningar som inte får förstöra parsningen går till stderr. Loggar i follow-läge använder NDJSON – ett JSON-objekt per rad – så att en anropare kan bearbeta en ström stegvis utan att behöva vänta på en enda stor array.

Dockup använder --json i hela sitt kommandogränssnitt. Med 135 kommandon skulle det vara skört att kräva att en agent minns flaggor. CLI-referensen och det paketerade skill-paketet innehåller de versionsanpassade kommandoinstruktioner som agenten bör följa.

Den viktiga designegenskapen är inte smart upptäckt. Det viktiga är att agenten får aktuell, strukturerad operativ vägledning och inte hittar på en flagga utifrån en gammal prompt.

Hur bör riktiga exitkoder styra deployment-automation?

Operativsystemets exitkod är den mest portabla signalen för framgång som finns tillgänglig för shellskript, CI-runners och kodningsagenter. Exit 0 betyder att kommandot uppnådde sitt definierade resultat. En kod som inte är noll betyder att anroparen måste välja mellan återställning, eskalering eller avslut.

Det här shellfragmentet är medvetet odramatiskt:

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 söker inte efter ordet ”success” i stdout. Det antar inte att ett HTTP 202-svar betyder att produktionen är redo. Det överlåter definitionen av framgång till CLI:t och vidarebefordrar felet till den överordnade processen.

Riktiga exitkoder är lika viktiga för engångskommandon i en container. Dockups PRO-kommando exec returnerar stdout, stderr och den faktiska exitkoden för kommandot:

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

En agent kan därför skilja mellan en slutförd migration och ett kommando som bara startade. Detta är en grundläggande princip i produktionsskyddsräcken för AI-agenter.

Hur ersätter väntan på slutstatus skör polling?

Handskrivna polling-loopar introducerar dolda policybeslut: hur ofta polling ska ske, vilka tillstånd som är slutgiltiga, hur länge man ska vänta, om ett tillfälligt nätverksfel ska återställa timern och vad som ska hända när en container startar om.

En agent löper särskilt stor risk att fatta fel beslut, eftersom den kanske inte känner till plattformens fullständiga tillståndsmaskin. Plattformen bör äga väntesemantiken.

Dockup tillhandahåller två användbara mönster:

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

deploy --wait väntar uttryckligen. push väntar som standard efter att pushen har gjorts och releasen har triggats; --no-wait stänger av väntan. Båda returnerar en exitkod som återspeglar slutresultatet.

Loggvisning i follow-läge följer samma idé:

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

Strömmen avslutas när builden når framgång eller fel. Ett slutligt NDJSON-objekt markerar done:true, och en misslyckad build avslutas med en kod som inte är noll. Anroparen behöver inte implementera ytterligare en pollinglösning.

För att kontrollera applikationens tillgänglighet efter en deployment returnerar Dockups uptime-kommando kontroller på minutnivå, genomsnittlig svarstid och p95:

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

Väntan och övervakning är separata begrepp. --wait svarar på om den här deploymenten nådde ett slutgiltigt resultat; uptime visar hur den körande tjänsten betedde sig över tid.

Vilka felkoder bör en agent förstå?

Stabila felkategorier låter en agent vidta en avgränsad åtgärd utan att tolka varje möjlig meddelandetext. Dockup exponerar koder som:

Felkod	Betydelse	Säker reaktion för agenten
not_logged_in	Ingen användbar token	Stoppa och begär autentisering
not_linked	Inget .dockup-mål för push	Lös målet eller skicka med målet
no_target	Tjänsten kunde inte identifieras	Kör services --json
needs_confirm	Destruktiv åtgärd saknar godkännande	Fråga en människa
deploy_trigger_failed	Deployment kunde inte startas	Rapportera API-felet
deploy_failed	Build eller deployment misslyckades	Läs buildloggarna
deploy_timeout	Körningen pågick fortfarande efter väntetidsgränsen	Rapportera osäkerhet eller förläng väntetiden medvetet

Felmeddelandet förblir användbar kontext, men koden styr den första grenen. Det gör automationen motståndskraftig mot tydligare formuleringar eller lokalisering.

Bekräftelse är också en del av protokollet. Ett destruktivt kommando bör inte fortsätta tyst bara för att anroparen är icke-interaktiv. Dockup vägrar sådana åtgärder utan --yes och returnerar needs_confirm. En autonom agent ser en fråga, inte ett hinder som ska kringgås.

Säkerhetsmodellen utforskas vidare i säkerhetsrutiner.

Vilket är minimikontraktet för ett produktionsklart CLI?

Ett produktionsklart CLI för AI-agenter bör uppfylla ett litet men strikt kontrakt:

1. Alla läs- och skrivåtgärder har maskinläsbara utdata.
2. Fel producerar en process-exitkod som inte är noll.
3. Asynkrona ändringar kan vänta på ett dokumenterat slutgiltigt tillstånd.
4. Hemliga värden returneras aldrig av läskommandon.
5. Destruktiva åtgärder kräver uttrycklig bekräftelse.
6. Fel har stabila koder som kan användas för förgrening.
7. CLI-paketet och agentinstruktionerna förblir versionsanpassade.
8. Ändringar sparas i ett audit trail.

Dockups skill-paket omvandlar dessa regler till standardbeteende för Claude Code och Codex. Det instruerar agenten att använda JSON, autentisera med DOCKUP_TOKEN, hitta exakta mål, göra deployment med --wait, skydda autentiseringsuppgifter och stoppa vid needs_confirm.

Jämför den här modellen med de bredare koncepten i agent skills jämfört med MCP. Ett skill-paket tillhandahåller operativ kunskap; CLI:t förblir det körbara gränssnittet vars exitstatus och utdata definierar sanningen.

En testmatris för ett agentinriktat kommando

Innan du exponerar ett infrastrukturkommando för en agent bör du testa mer än happy path:

Test	Förväntat beteende
Giltig begäran	JSON-resultat och exit 0
Ogiltig token	Stabil autentiseringskod och exitkod som inte är noll
Okänt mål	Stabil målkod och ingen ändring
Långvarig deployment	Väntar tills slutstatus eller timeout
Misslyckad deployment	Exitkod som inte är noll plus diagnostiserbart deployment-ID
Destruktivt godkännande saknas	needs_confirm, ingen radering
Läsning av hemlighet	Nyckelmetadata synlig, värdet maskerat
Varning under JSON-utdata	Varning på stderr, giltig JSON på stdout

Den här matrisen är mer värdefull än en polerad progress spinner. Mänsklig formatering kan läggas ovanpå; ett deterministiskt maskinkontrakt kan inte återskapas i efterhand.

Dockups CLI-dokumentation visar de konkreta kommandona bakom den här modellen, medan AI-driven utveckling förklarar den större övergången från manuell verktygsanvändning till agentstyrda arbetsflöden.

Betrakta observability som en del av kommandokontraktet

En ändring som riktar sig till en agent bör returnera identifierare som möjliggör senare utredning. Ett deploymentsvar behöver målet och deployment-ID:t; en skapad databas behöver en stabil slug; en snapshot av en volym behöver sitt snapshot-ID. Utan dessa referenser kan agenten beskriva en händelse, men kan inte på ett tillförlitligt sätt inspektera, försöka igen eller återställa den.

Audit trail slutför kontraktet. Strukturerad output förklarar ett enskilt anrop, medan auditposter kopplar samman flera anrop över tid. Tillsammans gör de det möjligt för operatörer att avgöra om agenten agerade på avsedd resurs och om ett senare återställningskommando hänvisade till samma produktionshändelse.

Håll gränssnittet odramatiskt

Ett pålitligt CLI för AI-agenter bör vara förutsägbart vid framgång, fel, timeout och nya försök.

Slutligt gränssnittstest

CLI:t för AI-agenter måste misslyckas sanningsenligt.

Ta arbetsflödet i produktion

Testa kontraktet från ett shell först: verifiera JSON-parsning, en lyckad exitkod, ett framtvingat fel, en timeout och en blockerad destruktiv åtgärd innan du delegerar produktionsåtkomst.

npm install -g dockup-cli
dockup skill install

Det första kommandot installerar CLI:t. Det andra installerar det matchande Dockup-skill-paketet för Claude Code och Codex. Kom igång gratis på app.dockup.ai.

Vanliga frågor

Vad gör ett CLI lämpligt för AI-agenter?

Det behöver strukturerade utdata, riktiga exitkoder, väntan på slutstatus, stabila felkoder, maskering av hemligheter och uttrycklig bekräftelse för destruktiva åtgärder.

Varför är JSON bättre än mänskligt formaterade CLI-utdata för agenter?

JSON tillhandahåller stabila fältnamn och typer. Agenten behöver inte dra slutsatser från färger, tabeller, interpunktion eller föränderliga formuleringar.

Varför är en accepterad deployment-begäran inte samma sak som framgång?

Att begäran accepterades bevisar bara att plattformen köade åtgärden. Den efterföljande builden, starten, hälsokontrollen och trafikväxlingen kan fortfarande misslyckas.

Vilken är Dockups standard-timeout för väntan vid deployment?

Standard-timeouten för dockup deploy --wait är 900 sekunder och kan ändras med det dokumenterade alternativet --timeout.

Hur bör en agent reagera på needs_confirm?

Den bör stoppa och be om uttryckligt godkännande. Koden betyder att den begärda åtgärden är destruktiv och avsiktligt inte utfördes.