---
title: "Headless und CI · Alran-Code-Doku"
url: https://alran.dev/de/docs/headless
locale: de
updated: 2026-11-16
---

[Doku](https://alran.dev/de/docs)Automatisieren

# Headless und CI

`alran exec` erledigt eine Aufgabe ohne TUI: in Skripten, in der CI, in Stapelläufen.

Auf dieser Seite

[Wie führe ich eine Aufgabe ohne TUI aus?](#run) [Das Ergebnis im Code lesen](#output) [Optionen](#options) [In der CI](#ci) [Exit-Codes](#exit) [Häufige Fragen](#faq)

## Wie führe ich eine Aufgabe ohne TUI aus? {#run}

```bash
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 {#output}

```bash
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:

```bash
alran exec --output-schema schema.json --output-format json "Schätz den Aufwand jedes offenen Issues"
```

## Optionen {#options}

| 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 {#ci}

Leg unter [ai.ottili.one/api-keys](https://ai.ottili.one/api-keys) einen API-Schlüssel an, speicher ihn als Secret und gib ihn als `ALRAN_API_KEY` mit:

```yaml
# .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 {#exit}

| 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](https://alran.dev/de/docs/errors).

## Häufige Fragen {#faq}

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.

[ZurückMCP-Server](https://alran.dev/de/docs/mcp) [WeiterNode.js und ACP](https://alran.dev/de/docs/sdk)
