# Wenn die CLI abbricht

Die häufigsten Abbrüche der CLI in der Reihenfolge, in der sie auftreten — mit der Meldung, die Sie sehen, dem Exit-Code, seiner Bedeutung und dem Weg zurück. Jede Lösung verweist auf die zuständige Seite.

> **Typ:** fehlerhilfe
> **Für wen:** Wer einen Befehl abgesetzt hat und statt eines Ergebnisses eine Meldung mit `✗` oder ein `{"error": …}` sieht
> **Voraussetzung:** der Exit-Code des Aufrufs (`echo $?` direkt nach dem Befehl) — und ein Aufruf über `node …/dist/main.js` oder `szenera`, nicht über `pnpm run`

| Symptom | Bedeutung | Lösung |
|---|---|---|
| „Unbekannter Befehl „device lister"." und darunter die ganze Übersicht (Exit 1) | Die Wörter treffen keinen Befehl des Registers: Tippfehler, falsche Reihenfolge (`list device`) oder eine Flagge ohne `=`, die als Wort gelesen wurde. | Den Befehl aus der Übersicht wählen; Flaggen tragen ihren Wert am Gleichheitszeichen (`--limit=20`). Siehe [Befehle für Ihre Organisation](/de/cli/commands-organization). |
| „„device list" kennt die Flagge „--state" nicht. Bekannt sind: …" (Exit 1) | Eine unbekannte Flagge ist ein Fehler, kein stiller Hinweis — die Meldung zählt die gültigen auf. | Eine der genannten Flaggen nehmen; `szenera <befehl> --help` erklärt sie. |
| „„--limit" braucht einen Wert: --limit=<anzahl>." (Exit 1) | Die Flagge stand ohne Gleichheitszeichen; `--limit 20` gibt es nicht. | `--limit=20` schreiben. |
| „„device get" braucht <id> — …" (Exit 1) | Eine Pflicht-Stellung fehlt. | Die Kennung anhängen, wie `--help` es zeigt. |
| „„scn_01K…" ist keine Kennung für ein Medium: erwartet wird ast_…" (Exit 1) | Der Präfix der Kennung passt nicht zum Befehl; es ging kein Aufruf hinaus. | Die richtige Kennung nehmen — `ast_` Medium, `scn_` Szene, `pll_` Playlist, `sch_` Programm, `ply_` Display, `dev_` Gerät. |
| „… wandert in den Papierkorb. Wenn das gewollt ist: --yes anhängen." (Exit 1) | Ein unumkehrbarer Eingriff ohne Zustimmung im Aufruf. | `--yes` anhängen, wenn die Folge gewollt ist. |
| „Keine Konfiguration gefunden — die Kommandozeile weiß nicht, mit welcher Umgebung sie sprechen soll.“ (Exit 2) | Weder eine Datei an einem der beiden Orte noch `SZENERA_BASE_URL`. | Profil anlegen oder `SZENERA_BASE_URL` und `SZENERA_API_KEY` setzen; siehe [Profile und Ausweis](/de/cli/profiles-and-credentials). |
| „Unbekanntes Profil „staging". … führt: dev, prod." (Exit 2) | `--profile=` oder `SZENERA_PROFILE` nennt einen Namen, den die Datei nicht führt. | Einen der genannten Namen wählen. |
| „„asset delete" ist im Profil „prod" gesperrt — das Profil ist schreibgeschützt." (Exit 2) | Ein verändernder Befehl trifft auf ein schreibgeschütztes Profil — oder auf eines ohne die Angabe, denn dann gilt `true`. | Wenn das Profil schreiben darf: `readOnly: false` setzen; siehe [Profile und Ausweis](/de/cli/profiles-and-credentials). |
| „Kein API-Schlüssel: erwartet wird ein Wert mit dem Präfix 'ak_' oder 'opk_' …" (Exit 2) | Der Wert im Profil oder in `SZENERA_API_KEY` ist kein Schlüssel — abgeschnitten, vertauscht, leer. | Den Klartext aus dem Portal übernehmen; siehe [Profile und Ausweis](/de/cli/profiles-and-credentials). |
| „„whoami" braucht einen Ausweis, das Profil „…" trägt keinen." (Exit 1) | Das Profil hat `credential: {"kind": "none"}` oder gar keinen; nur `health` und `health public` laufen so. | `SZENERA_API_KEY=ak_…` mitgeben oder `credential` im Profil setzen. |
| HTTP 401 (Exit 3) trotz gesetztem Schlüssel | Der Schlüssel gilt nicht: widerrufen, abgelaufen — oder das Profil zeigt auf eine andere Umgebung als die, für die der Schlüssel ausgestellt wurde. | `szenera whoami --profile=<name>` je Profil; neuen Schlüssel erzeugen; siehe [Profile und Ausweis](/de/cli/profiles-and-credentials). |
| HTTP 403 `Permission.Denied` (Exit 4) | Der Ausweis gilt, aber das Recht fehlt — oder die Route verlangt ein Recht, das ein Schlüssel nicht tragen darf (etwa `identity.device.list`). | Spalte „Schlüssel" der Befehlsseiten prüfen; Rechte des Schlüssels erweitern oder ein Profil mit Kennwort-Anmeldung nehmen. |
| „Die Anfrage an „composition.scenes.update" entspricht nicht dem Vertrag:" mit Feldpfaden (Exit 1) | Ihre Eingabe — meist eine Datei hinter `--document` oder `--entries` — hält das Schema nicht; es ging kein Netzpaket hinaus. | Die genannten Felder in der Datei korrigieren; siehe [Ausgabe als JSON und Exit-Codes](/de/cli/output-and-exit-codes). |
| „Die Antwort auf „…" widerspricht dem Vertrag, den diese CLI (0.1.0) kennt." (Exit 9) | Versatz der Stände: Die Gegenstelle ist älter oder neuer als die CLI — nicht: dort ist etwas kaputt. | `--raw` anhängen; die Rohantwort auf der Standardausgabe zeigt, welches Feld fehlt. CLI aus dem passenden Stand bauen; siehe [Ausgabe als JSON und Exit-Codes](/de/cli/output-and-exit-codes). |
| HTTP 409 (Exit 6) bei `scene update`, `playlist update`, `role update` | Die erwartete Fassung stimmt nicht mehr — jemand hat dazwischen geändert. | Ohne `--version` erneut aufrufen (der Befehl liest die Fassung dann selbst); `scene update --retry` wiederholt einmal von allein. |
| HTTP 422 (Exit 7) mit `Scene.PublishValidationFailed` | Die Live-Prüfung des Dokuments schlug an — ein Medium ist weg, eine Vorlage gelöscht. | Ursache beheben; Befunde lassen sich hier nicht übergehen. |
| HTTP 429 (Exit 8) | Zu viele Aufrufe; `retryAfterSeconds` steht im Fehler. | So lange warten, dann erneut; siehe [Skripte und CI](/de/cli/scripts-and-ci). |
| `Network.RequestFailed`, „fetch failed" (Exit 10) | Gar keine HTTP-Antwort: falsche Adresse, kein Netz, kein Name. | `SZENERA_BASE_URL` bzw. `services` im Profil prüfen; `szenera health` braucht keinen Ausweis und trennt Netz von Anmeldung. |
| `health` endet mit Exit 9 | Die Umgebung meldet sich nicht bereit — HTTP 503 auf `GET /health/ready`. | Warten und erneut prüfen; die Tabelle nennt die Prüfung, die rot ist. |
| Exit 11 nach `asset upload`, `device get-command --wait` | Der Vorgang kam durch und endete rot: Verarbeitung gescheitert, Befehl `failed`. | Den Befund im Fehler lesen; `asset reprocess` ist der Weg zurück für ein Medium im Zustand `error`; siehe [Skripte und CI](/de/cli/scripts-and-ci). |
| Exit 12 „Zeitlimit … erreicht — der Ausgang ist unbekannt." | Das Zeitlimit griff; der Vorgang läuft womöglich weiter. | Nicht blind wiederholen — erst mit `asset get` oder `device get-command` nachsehen, dann mit größerem `--timeout` erneut; siehe [Skripte und CI](/de/cli/scripts-and-ci). |
| „„abc" ist keine Dauer. Erlaubt sind 500ms, 90s, 20m, 2h — oder eine Zahl in Sekunden." (Exit 1) | `--timeout` oder `--interval` trägt eine Form, die die CLI nicht kennt. | Eine der genannten Formen verwenden. |
| „„--limit=500" liegt außerhalb von 1…200." (Exit 1) | Mehr gibt der Vertrag je Seite nicht her. | `--limit=200` und `--all`; siehe [Skripte und CI](/de/cli/scripts-and-ci). |
| „Der Rumpf ist kein gültiges JSON" bei `api post` (Exit 1) | Die Shell hat den Rumpf verändert — Anführungszeichen, Dollarzeichen, Zeilenumbrüche. | Größere Rümpfe als Datei übergeben: `@rumpf.json`. |
| Jeder Fehler endet mit Exit 1, egal was passiert | Der Aufruf läuft über `pnpm run`; das verschluckt die Codes. | `node packages/cli/dist/main.js …` direkt aufrufen; siehe [Ausgabe als JSON und Exit-Codes](/de/cli/output-and-exit-codes). |
| Die Ausgabe ist eine Tabelle, obwohl ein Skript sie liest — oder JSON im Terminal | Die Form folgt der Standardausgabe: Terminal heißt Tabelle, Röhre heißt JSON; `SZENERA_OUTPUT` kann das überschreiben. | `--json` oder `--table` erzwingen. |
| Der Befehl endet mit Exit 0, aber `ergebnis.json` enthält `.daten` nicht | Es gibt keine Hülle: Die Standardausgabe trägt die Nutzlast direkt. | `.items[]` statt `.daten.items[]` lesen; siehe [Ausgabe als JSON und Exit-Codes](/de/cli/output-and-exit-codes). |

## Weiterführendes

- [Profile und Ausweis](/de/cli/profiles-and-credentials)
- [Ausgabe als JSON und Exit-Codes](/de/cli/output-and-exit-codes)
- [Skripte und CI](/de/cli/scripts-and-ci)