CLI-Design für AI-Agenten: JSON, Exit-Codes und Warten

Ein AI-Agent-CLI ist nicht einfach nur ein Command-Line-Tool für Menschen, das zufällig von einem Modell aufgerufen werden kann. Es ist ein operatives Protokoll. Der Agent benötigt deterministische Eingaben, strukturierte Ausgaben, aussagekräftige Exit-Codes, stabile Fehlerkategorien und eine Möglichkeit zu warten, bis die asynchrone Infrastruktur einen finalen Status erreicht.

Ohne diesen Vertrag muss ein Agent den Erfolg aus Formulierungen wie „Deployment gestartet“ ableiten. Diese Schlussfolgerung ist gefährlich, weil eine akzeptierte Anfrage später während des Builds, der Health Checks, des Containerstarts oder der Umschaltung des Traffics fehlschlagen kann.

Warum ist ein vermuteter Deployment-Erfolg gefährlich?

Die meisten Infrastrukturvorgänge sind asynchron. Eine API kann ein Deployment akzeptieren und innerhalb von Millisekunden eine ID zurückgeben, während der eigentliche Build mehrere Minuten dauert. Wenn ein Agent bereits bei der Annahme Erfolg meldet, basieren alle nachfolgenden Schritte auf einer falschen Annahme.

Der Unterschied:

Ereignis	Was es beweist	Was es nicht beweist
Anfrage akzeptiert	Die Plattform hat die Anfrage verstanden	Dass der Code gebaut wurde
Build abgeschlossen	Ein Image oder Artefakt wurde erstellt	Dass die App gestartet ist
Health Gate bestanden	Die neue Instanz hat wie erforderlich geantwortet	Dass die Business-Flows funktionieren
Traffic umgeschaltet	Das Release ist aktiv geworden	Dass es dauerhaft fehlerfrei bleibt
Uptime-Beobachtung	Der Service bleibt erreichbar	Dass jedes Feature korrekt funktioniert

Ein Mensch erkennt den Unterschied möglicherweise in einem Dashboard. Für einen textbasiert arbeitenden Agenten muss er in der Schnittstelle kodiert sein.

Der Command-Vertrag von Dockup trennt das Einreihen von der Fertigstellung. Ein Deployment ohne --wait wird sofort mit waited:false zurückgegeben; ein Deployment mit --wait blockiert, bis Erfolg, Fehler oder ein Timeout eintritt:

dockup deploy production/api --wait --json

Das Standard-Timeout beträgt 900 Sekunden. Der Command wird erst nach einem erfolgreichen finalen Status mit 0 beendet. Bei einem nicht erfolgreichen Ergebnis wird er mit deploy_failed oder deploy_timeout beendet.

Welche Vorteile bietet ein strukturiertes JSON-CLI für einen AI-Agenten?

Strukturiertes JSON ersetzt die Interpretation von Prosa durch benannte Felder. Der Agent kann status, deploymentId, target oder code direkt auslesen, statt von Satzzeichen, Farben, Spaltenbreiten oder Formulierungen abhängig zu sein.

Ein erfolgreiches Ergebnis kann als Daten verarbeitet werden:

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

Ein Fehler verwendet dieselbe Transportstruktur:

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

Die wichtigste Designregel lautet: JSON wird auf stdout geschrieben, während Warnungen, die das Parsing nicht beschädigen dürfen, auf stderr ausgegeben werden. Logs im Follow-Modus verwenden NDJSON – ein JSON-Objekt pro Zeile –, sodass ein Aufrufer den Stream inkrementell verarbeiten kann, ohne auf ein riesiges Array warten zu müssen.

Dockup verwendet --json über die gesamte Command-Oberfläche hinweg. Bei 135 Commands wäre es fehleranfällig, von einem Agenten zu verlangen, sich die Flags aus dem Gedächtnis herzuleiten. Die CLI-Referenz und der bereitgestellte Skill enthalten versionskonforme Command-Anweisungen, die der Agent befolgen soll.

Die entscheidende Eigenschaft ist nicht eine besonders clevere Discovery. Entscheidend ist, dass der Agent aktuelle, strukturierte Anweisungen für den Betrieb erhält und kein Flag aus einem veralteten Prompt erfindet.

Wie sollten echte Exit-Codes die Deployment-Automatisierung steuern?

Der Exit-Code des Betriebssystems ist das portabelste Erfolgssignal für Shell-Skripte, CI-Runner und Coding-Agenten. Exit 0 bedeutet, dass der Command sein definiertes Ergebnis erreicht hat. Ein von 0 verschiedener Code bedeutet, dass der Aufrufer in Recovery, Eskalation oder Beendigung verzweigen muss.

Dieses Shell-Snippet ist absichtlich unspektakulär:

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

Es durchsucht stdout nicht nach dem Wort „success“. Es nimmt nicht an, dass eine HTTP-202-Antwort bedeutet, dass die Produktion bereit ist. Stattdessen überlässt es dem CLI die Definition von Erfolg und reicht Fehler an den übergeordneten Prozess weiter.

Echte Exit-Codes sind auch für einmalige Commands innerhalb eines Containers entscheidend. Der PRO-Command exec von Dockup gibt stdout, stderr und den tatsächlichen Exit-Code des Commands zurück:

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

Ein Agent kann dadurch zwischen einer abgeschlossenen Migration und einem Command unterscheiden, der lediglich gestartet wurde. Dies ist ein grundlegendes Prinzip von Production Guardrails für AI-Agenten.

Wie ersetzt das Warten auf einen finalen Status fragiles Polling?

Selbst geschriebene Polling-Schleifen führen zu versteckten Richtungsentscheidungen: Wie oft soll abgefragt werden? Welche Stati sind final? Wie lange soll gewartet werden? Soll ein vorübergehender Netzwerkfehler den Timer zurücksetzen? Was soll passieren, wenn ein Container neu gestartet wird?

Ein Agent trifft diese Entscheidungen besonders leicht falsch, weil er möglicherweise nicht die vollständige State Machine der Plattform kennt. Die Plattform sollte die Warte-Semantik selbst verwalten.

Dockup bietet zwei nützliche Muster:

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

deploy --wait wartet ausdrücklich. push wartet standardmäßig nach dem Push und dem Auslösen des Releases; --no-wait deaktiviert dieses Verhalten. Beide Commands geben einen Exit-Code zurück, der das finale Ergebnis widerspiegelt.

Das Folgen von Logs folgt demselben Prinzip:

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

Der Stream endet, sobald der Build Erfolg oder Fehler erreicht. Ein abschließendes NDJSON-Objekt markiert done:true, und ein fehlgeschlagener Build wird mit einem Exit-Code ungleich null beendet. Der Aufrufer benötigt keine zweite Polling-Implementierung.

Für die Verfügbarkeit einer Anwendung nach dem Deployment liefert Dockups Uptime-Command Prüfungen im Minutentakt, die durchschnittliche Antwortzeit und p95:

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

Warten und Monitoring sind getrennte Konzepte. --wait beantwortet die Frage, ob dieses Deployment einen finalen Status erreicht hat; Uptime zeigt, wie sich der laufende Service über einen Zeitraum verhalten hat.

Welche Fehlercodes sollte ein Agent verstehen?

Stabile Fehlerkategorien ermöglichen es einem Agenten, eine begrenzte Aktion auszuführen, ohne jede mögliche Meldung interpretieren zu müssen. Dockup stellt unter anderem folgende Codes bereit:

Fehlercode	Bedeutung	Sichere Reaktion des Agenten
not_logged_in	Kein verwendbarer Token vorhanden	Anhalten und Authentifizierung anfordern
not_linked	Kein .dockup-Target für push vorhanden	Target auflösen oder übergeben
no_target	Service konnte nicht identifiziert werden	services --json ausführen
needs_confirm	Für die destruktive Aktion fehlt die Freigabe	Einen Menschen fragen
deploy_trigger_failed	Deployment konnte nicht gestartet werden	API-Fehler melden
deploy_failed	Build oder Deployment ist fehlgeschlagen	Build-Logs lesen
deploy_timeout	Nach Ablauf des Wartezeitlimits noch nicht abgeschlossen	Unsicherheit melden oder bewusst verlängern

Die Fehlermeldung liefert weiterhin nützlichen Kontext, aber der Code steuert den ersten Verarbeitungsschritt. Dadurch bleibt die Automatisierung auch bei klareren Formulierungen oder einer Lokalisierung robust.

Auch die Bestätigung ist Teil des Protokolls. Ein destruktiver Command darf nicht stillschweigend fortfahren, nur weil der Aufrufer nicht interaktiv ist. Dockup verweigert solche Vorgänge ohne --yes und gibt needs_confirm zurück. Ein autonomer Agent sieht damit eine Frage und keine zu umgehende Schranke.

Das Sicherheitsmodell wird ausführlicher in den Security Best Practices erläutert.

Wie sieht der minimale Vertrag für ein produktionsreifes CLI aus?

Ein produktionsreifes AI-Agent-CLI sollte einen kleinen, aber strengen Vertrag erfüllen:

1. Jede Lese- und Schreiboperation bietet maschinenlesbare Ausgaben.
2. Ein Fehler führt zu einem Exit-Code ungleich null.
3. Asynchrone Änderungen können auf einen dokumentierten finalen Status warten.
4. Secret-Werte werden von Read-Commands niemals zurückgegeben.
5. Destruktive Aktionen erfordern eine ausdrückliche Bestätigung.
6. Fehler verfügen über stabile, für Verzweigungen geeignete Codes.
7. Das CLI-Paket und die Agent-Anweisungen bleiben versionskonform.
8. Änderungen werden in einem Audit Trail erfasst.

Der Skill von Dockup macht diese Regeln für Claude Code und Codex zum Standardverhalten. Er weist den Agenten an, JSON zu verwenden, sich mit DOCKUP_TOKEN zu authentifizieren, exakte Targets zu ermitteln, mit --wait zu deployen, Zugangsdaten zu schützen und bei needs_confirm anzuhalten.

Vergleiche dieses Modell mit den übergeordneten Konzepten in Agent Skills vs. MCP. Ein Skill stellt Betriebswissen bereit; das CLI bleibt die ausführbare Schnittstelle, deren Exit-Status und Ausgabe die Wahrheit definieren.

Eine Testmatrix für einen agentenorientierten Command

Bevor du einen Infrastruktur-Command für einen Agenten bereitstellst, solltest du mehr als nur den Happy Path testen:

Test	Erwartetes Verhalten
Gültige Anfrage	JSON-Ergebnis und Exit 0
Ungültiger Token	Stabiler Auth-Code und Exit-Code ungleich null
Unbekanntes Target	Stabiler Target-Code und keine Änderung
Lang laufendes Deployment	Wartet bis zum finalen Status oder Timeout
Fehlgeschlagenes Deployment	Exit-Code ungleich null plus nachvollziehbare Deployment-ID
Fehlende Freigabe für destruktive Aktion	needs_confirm, keine Löschung
Secret auslesen	Schlüsselmetadaten sichtbar, Wert maskiert
Warnung während der JSON-Ausgabe	Warnung auf stderr, gültiges JSON auf stdout

Diese Matrix ist wertvoller als ein aufwendig gestalteter Progress-Spinner. Eine menschenfreundliche Darstellung kann darauf aufbauen; ein deterministischer Maschinenvertrag lässt sich nachträglich nicht rekonstruieren.

Die Dockup CLI-Dokumentation zeigt die konkreten Commands hinter diesem Modell, während AI-gestützte Entwicklung den umfassenderen Wandel von der manuellen Tool-Nutzung zu agentengesteuerten Workflows erläutert.

Behandle Observability als Teil des Command-Vertrags

Eine Änderung, die von einem Agenten ausgeführt wird, sollte IDs zurückgeben, die spätere Untersuchungen ermöglichen. Eine Deployment-Antwort benötigt das Target und die Deployment-ID; eine erstellte Datenbank benötigt einen stabilen Slug; ein Volume-Snapshot benötigt seine Snapshot-ID. Ohne diese Referenzen kann der Agent zwar ein Ereignis beschreiben, es aber nicht zuverlässig untersuchen, wiederholen oder rückgängig machen.

Der Audit Trail vervollständigt den Vertrag. Strukturierte Ausgaben erklären einen einzelnen Aufruf, während Audit-Aufzeichnungen mehrere Aufrufe über die Zeit hinweg miteinander verknüpfen. Gemeinsam ermöglichen sie es Betreibern festzustellen, ob der Agent auf der vorgesehenen Ressource gehandelt hat und ob sich ein späterer Recovery-Command auf dasselbe Produktionsevent bezog.

Halte die Schnittstelle unspektakulär

Ein zuverlässiges AI-Agent-CLI sollte sich bei Erfolg, Fehler, Timeout und Wiederholung erwartbar verhalten.

Abschließender Schnittstellentest

Das AI-Agent-CLI muss wahrheitsgemäß fehlschlagen.

Überführe den Workflow in die Produktion

Teste den Vertrag zunächst in einer Shell: Überprüfe das JSON-Parsing, einen erfolgreichen Exit, einen erzwungenen Fehler, ein Timeout und einen blockierten destruktiven Vorgang, bevor du den Produktionszugriff delegierst.

npm install -g dockup-cli
dockup skill install

Der erste Command installiert das CLI. Der zweite installiert den passenden Dockup-Skill für Claude Code und Codex. Starte kostenlos auf app.dockup.ai.

FAQ

Was macht ein CLI für AI-Agenten geeignet?

Es benötigt strukturierte Ausgaben, echte Exit-Codes, das Warten auf einen finalen Status, stabile Fehlercodes, das Maskieren von Secrets und eine ausdrückliche Bestätigung für destruktive Vorgänge.

Warum ist JSON für Agenten besser als eine menschenfreundlich formatierte CLI-Ausgabe?

JSON stellt stabile Feldnamen und Datentypen bereit. Der Agent muss die Bedeutung nicht aus Farben, Tabellen, Satzzeichen oder sich ändernder Prosa ableiten.

Warum ist eine akzeptierte Deployment-Anfrage kein Erfolg?

Die Annahme beweist lediglich, dass die Plattform den Vorgang eingereiht hat. Der anschließende Build, der Start, das Health Gate und die Traffic-Umschaltung können weiterhin fehlschlagen.

Wie lang ist das Standard-Timeout für das Warten bei Dockup-Deployments?

Das Standard-Timeout für dockup deploy --wait beträgt 900 Sekunden und kann mit der dokumentierten --timeout-Option geändert werden.

Wie sollte ein Agent auf needs_confirm reagieren?

Er sollte anhalten und eine ausdrückliche Freigabe anfordern. Der Code bedeutet, dass die angeforderte Aktion destruktiv ist und absichtlich nicht ausgeführt wurde.