DokuAutomatisieren
Headless und CI
alran exec erledigt eine Aufgabe ohne TUI: in Skripten, in der CI, in Stapelläufen.
Wie führe ich eine Aufgabe ohne TUI aus?
alran exec "Schreib einen Test für den Datumsparser und bring ihn zum Laufen"Es gibt die Antwort aus und beendet sich. Der Exit-Code sagt deinem Skript, ob es geklappt hat.
Das Ergebnis im Code lesen
alran exec --output-format json "Liste die TODO-Kommentare in src/"
alran exec --output-format stream-json "Behebe die Lint-Fehler" | jq .
alran exec -o zusammenfassung.md "Fass zusammen, was sich seit dem letzten Tag geändert hat"--output-schema nimmt ein JSON-Schema (Datei oder direkt), dem die Antwort entsprechen muss, damit du Daten bekommst statt Prosa:
alran exec --output-schema schema.json --output-format json "Schätz den Aufwand jedes offenen Issues"Optionen
| Option | Was sie tut |
|---|---|
--cwd <pfad> | Der Arbeitsordner |
--file <pfad> | Eine Datei anhängen (mehrfach möglich) |
--input - | Den Prompt von stdin lesen; --input-format json für strukturierte Eingaben |
--model <anbieter/modell> | Ein anderes Modell für diesen Lauf |
--effort <stufe> | Reasoning-Aufwand für diesen Lauf |
--permission <richtlinie> | smart (Standard), full oder off |
--timeout <dauer> | Abbrechen nach zum Beispiel 30s oder 2m |
--max-steps <anzahl> | Abbrechen nach so vielen Schritten |
--session <id> / --continue | In einer bestehenden Sitzung laufen |
--mode lightweight | Keine Werkzeuge, keine Dateien: eine schnelle Antwort |
--prompt-mode <modus> | tui (Standard), coding oder work |
--diagnostics-dir <pfad> | Begrenzte Diagnosedaten eines gescheiterten Laufs speichern |
In der CI
Leg unter ai.ottili.one/api-keys einen API-Schlüssel an, speicher ihn als Secret und gib ihn als ALRAN_API_KEY mit:
# .github/workflows/alran.yml
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 24 }
- run: npm install -g alran
- run: alran exec --permission smart --timeout 10m "Prüf diese Änderung und nenn riskante Stellen"
env:
ALRAN_API_KEY: ${{ secrets.ALRAN_API_KEY }}alran exec review prüft gestagte, ungestagte und neue lokale Änderungen.
Exit-Codes
| Code | Bedeutung |
|---|---|
0 | Der Lauf war erfolgreich |
2 | Die Kommandozeile war falsch: fehlender Prompt, unbekanntes Flag oder unbrauchbares Modell |
3 | Die Konfiguration ist kaputt — Alran öffnen und /doctor ausführen |
4 | Der Lauf startete, aber Modell oder Laufzeitumgebung schlugen fehl |
6 | Der Lauf hat --timeout erreicht |
7 | Der Lauf hat --max-steps erreicht |
70 | Ein interner Fehler — bitte melden |
130 | Der Lauf wurde abgebrochen |
141 | Die Ausgabe-Pipe wurde vorzeitig geschlossen |
Konto-Befehle (alran auth, alran config, alran models, alran usage, alran billing) nutzen einen eigenen Satz: dort bedeutet 2 Anmeldung nötig, 4 die Platform ist nicht erreichbar und 5 dein Guthaben deckt die Anfrage nicht oder Claude hat keinen funktionierenden Anthropic-Schlüssel. Beide Listen stehen auf Fehlercodes.
Häufige Fragen
Wie führe ich Alran Code in der CI aus?
Leg auf der Ottili AI Platform einen API-Schlüssel an, speicher ihn als Secret und gib ihn als ALRAN_API_KEY mit. Rufe dann in deinem Workflow alran exec auf, zum Beispiel alran exec --permission smart --timeout 10m, um eine Änderung zu prüfen und riskante Stellen zu nennen. Der Exit-Code sagt deinem Skript, ob es geklappt hat.
Wie bekomme ich von alran exec JSON statt Prosa?
Mit alran exec --output-format json bekommst du ein JSON-Dokument, mit --output-format stream-json ein JSON-Ereignis pro Zeile, das du zum Beispiel mit jq weiterverarbeiten kannst. Soll die Antwort eine feste Form haben, übergib ein JSON-Schema mit --output-schema, und mit -o schreibst du das Ergebnis in eine Datei.
Was bedeuten die Exit-Codes von alran exec?
Null heißt, der Lauf war erfolgreich, 2 heißt, die Kommandozeile war falsch, 3 heißt, die Konfiguration ist kaputt, 4 heißt, Modell oder Laufzeitumgebung sind gescheitert, 6 heißt, der Lauf hat --timeout erreicht, 7 heißt, er hat --max-steps erreicht, 70 ist ein interner Fehler, 130 heißt, der Lauf wurde abgebrochen, und 141 heißt, die Ausgabe-Pipe wurde vorzeitig geschlossen. Die Konto-Befehle alran auth, alran config, alran models, alran usage und alran billing nutzen einen eigenen Satz; beide Listen stehen auf der Seite Fehlercodes.