> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Skripte, CI und Coding-Agenten

> Famulor sicher automatisieren: saubere Ausgabe, Exit-Codes, Bestätigungen, Probeläufe und ein Befehlsschema für Agenten

Die CLI ist für Skripte gebaut. Daten gehen an stdout, Meldungen an stderr, und jeder Fehler endet mit einem Exit-Code ungleich null.

## Standardmäßig sicher

* **Löschvorgänge und unumkehrbare Aktionen nur nach Rückfrage.** Das gilt für Löschvorgänge und für Aktionen wie den Kauf einer Nummer, die Übertragung eines Workspaces oder die Wiederherstellung einer alten Version. Im Terminal fragt die CLI vorher nach einer Bestätigung. In Skripten, in CI und in Coding-Agenten übergibst du `--yes`; ohne diese Option wird der Befehl nicht ausgeführt.
* **Probeläufe.** `--dry-run` zeigt die exakte Anfrage (Methode, URL, Header und Body) mit verborgenem API-Key an und sendet nichts.
* **Wiederholungen ohne Doppelbuchungen.** Ist das Anfragelimit erreicht, wartet die CLI die von der API genannte Zeit ab und versucht es erneut. Anfragen, die etwas anlegen, werden nach einem Timeout oder einem Nutzungslimit nie wiederholt, sodass ein Anruf nie zweimal ausgelöst wird. `--timeout` ist die Frist für den gesamten Befehl, Wartezeiten eingeschlossen.
* **Keine Abfragen, wenn niemand antworten kann.** In CI und innerhalb von Coding-Agenten wartet die CLI nie auf eine Eingabe.

```bash theme={null}
famulor delete-assistant <id> --yes
famulor create-call --assistant-id <id> --to-number +4930123456 --dry-run
```

## Beispiele

```bash theme={null}
# Namen aller Assistenten
famulor list-assistants --all --output jsonl | jq -r '.name'

# Aufzeichnung für alle Assistenten einschalten
famulor list-assistants --all --output jsonl | jq -r '.id' \
  | xargs -I{} famulor update-assistant {} --recording-enabled true

# Alle abgeschlossenen Anrufe speichern
famulor list-calls --status completed --all > calls.json
```

## Exit-Codes

| Code | Bedeutung |
| - | - |
| `0` | Erfolg |
| `1` | API- oder Netzwerkfehler |
| `2` | Bedienfehler, etwa eine unbekannte Option oder ein ungültiger Wert |
| `3` | Nicht angemeldet, oder die API hat die Zugangsdaten oder die Berechtigung abgelehnt |
| `4` | Nicht gefunden |
| `5` | Bei einer Bestätigungsabfrage abgebrochen |

## Fehler in Skripten

Schlägt ein Befehl fehl, bleibt stdout leer, sodass ein Fehler nie als Daten gelesen wird. Ist stderr kein Terminal, ist seine letzte Zeile der Fehler als JSON (eventuelle Warnungen stehen davor):

```json theme={null}
{"error":{"code":"not_found","message":"Not found (404 not_found): Call not found.","status":404,"exit_code":4}}
```

`code` ist der Fehlercode der API. Fehler ohne Antwort der API verwenden `network_error`, `timeout`, `invalid_response`, `usage_error` oder `auth_error`. `retry_after` gibt an, wie viele Sekunden du nach einem Anfragelimit warten solltest. `may_have_executed: true` bedeutet, dass eine Anfrage, die etwas anlegt, die API erreicht haben könnte, bevor die Verbindung abbrach. Prüfe das also, bevor du es erneut versuchst.

```bash theme={null}
famulor get-call <id> > call.json 2> error.log || tail -n 1 error.log | jq -r '.error.code'
```

## GitHub Actions

```yaml theme={null}
- uses: actions/setup-node@v4
  with:
    node-version: 22
- run: npm install --global famulor
- run: famulor list-calls --status failed --limit 50 --output jsonl
  env:
    FAMULOR_API_KEY: ${{ secrets.FAMULOR_API_KEY }}
```

## Coding-Agenten

Coding-Agenten wie Claude Code, Codex und Cursor können die CLI direkt verwenden:

* `famulor commands <topic>` findet Befehle. Außerhalb eines Terminals gibt der Befehl kompaktes JSON aus: Befehl, Zusammenfassung, Methode, Pfad und Bereich.
* `famulor <command> --help --output json` gibt das vollständige Schema eines Befehls aus: Argumente, Optionen, Typen, erlaubte Werte, Standardwerte, Grenzwerte, Pflichtfelder und ein Beispiel. `famulor commands --full --output json` macht das für jeden Befehl.
* Farben, Animationen und Abfragen schalten sich in CI und innerhalb von Coding-Agenten automatisch ab. Unumkehrbare Aktionen brauchen `--yes`.
* Fehlermeldungen sagen, was schiefgelaufen ist und was du als Nächstes ausführen solltest.

Meist genügt eine kurze Anweisung, zum Beispiel: „Verwende die `famulor` CLI. Finde Befehle mit `famulor commands <topic>` und lies die Details eines Befehls mit `famulor <command> --help --output json` nach. Probiere schreibende Befehle zuerst mit `--dry-run` aus.“

<Tip>
  Für die Arbeit im Dialog innerhalb eines KI-Assistenten eignet sich der [MCP-Server](/de/mcp/overview) besser. Er bietet dieselben Funktionen als Tools an.
</Tip>