JSON & Automatisierung

Die CLI ist dafür gemacht, per Skript gesteuert zu werden. Übergebe --json für maschinenlesbare Ausgabe, nutze sie in CI mit einem Token und ermittle das Schema jedes Befehls zur Laufzeit.

Der andere Empfänger dieser Ausgabe ist ein KI-Coding-Agent — Deployment aus Claude Code zeigt die JSON-Log-Befehle, die er ausführt, um ein Deployment zu prüfen.

--json überall

Füge --json zu jedem Befehl hinzu, um strukturierte Ausgabe zu erhalten. Die CLI schaltet auch automatisch auf JSON um, wenn stdout kein TTY ist.

lizard ps --json
lizard secrets list --json
lizard metrics --json

Streaming-Befehle

Bei Streaming-Befehlen (lizard up ohne --detach) gibt --json pro Zeile genau ein JSON-Objekt aus:

{ "event": "log", "line": "Step 1/8 : FROM node:20" }
{ "event": "log", "line": "..." }
{ "event": "deployed", "status": "running", "url": "https://app.onlizard.com" }

Der Build-Stream endet mit done oder error. Nach done gibt lizard up ohne --ci ein abschließendes Ereignis deployed, failed oder deploying mit status aus. Nur deployed enthält url (dies kann null sein). Nach error folgt kein abschließendes Ereignis, und der Befehl endet mit 1.

logs --json ist eine Momentaufnahme, kein Stream

lizard logs --json gibt die letzten 200 Zeilen zurück (überschreibbar mit --tail N, maximal 1000) und beendet sich dann. Warte nicht darauf, wenn du weitere Ausgabe erwartest. Für einen bestimmten Vorfall verwende --restart latest oder --restart <id>.

Fehler

Im JSON-Modus gibt ein fehlgeschlagener Befehl ein Fehlerobjekt auf stdout aus und endet mit einem Exit-Code ungleich null (siehe die Tabelle unter CI / Headless-Nutzung):

{
  "error": {
    "code": "ERROR",
    "status": null,
    "message": "Project \"my-projet\" not found.",
    "body": null
  }
}

code ist der Fehlercode der API, ein CLI-Code wie NOT_AUTHENTICATED oder PROJECT_DELETED oder ERROR für einen allgemeinen Fehler; falsche Flags ergeben Codes wie commander.unknownOption. status ist der HTTP-Status oder null, wenn die CLI scheiterte, bevor die API antwortete. body enthält die Antwort der API oder null.

Ohne Anmeldung scheitern Befehle mit NOT_AUTHENTICATED und Exit-Code 2. Außerhalb von CI enthält body.login Anmeldelinks (authUrl, authUrls) und eine instruction: Ein Agent kann dem Benutzer den Link geben und den Befehl danach erneut ausführen.

Schema-Erkennung

Gib die exakten Argumente, Optionen und Exit-Codes eines beliebigen Befehls aus:

lizard --help --json                 # whole tree + global flags + exit codes
lizard service set --help --json     # one command

Die Form der Antwort ist { cli, version, agents, command: { arguments, options, subcommands }, globalOptions, exitCodes }. Da sie aus deiner installierten Binärdatei erzeugt wird, passt sie immer zu deiner Version — ziehe sie fest codierten Flags vor.

CI / Headless-Nutzung

Authentifiziere dich mit einem Token und verknüpfe das Projekt explizit. Sonst deployt headless up in das Standardprojekt deines Kontos:

# Set LIZARD_TOKEN through your CI secret store.
lizard init --name my-project
lizard up --ci --service api --detach   # creates api on the first run

Prüfe Exit-Codes, um deine Pipeline zu verzweigen:

Ein Projekt- oder Service-Name, zu dem nichts passt, endet mit 1. lizard run, lizard sandbox exec und lizard sandbox ssh enden mit dem Exit-Code des Befehls selbst (127, wenn run den Befehl nicht findet).

--wait sorgt dafür, dass redeploy auf den Build wartet und darauf, dass das neue Deployment bereit ist. Ohne diese Option beendet sich der JSON-Modus mit 0, sobald Lizard die Build-Anfrage akzeptiert hat.

if lizard redeploy --service api --wait --json; then
  echo "Deploy succeeded"
else
  status=$?
  echo "Deploy failed with code $status" >&2
  lizard logs --build --json || true
  exit "$status"
fi

Aktualisiert 21. Oktober 2026