Famulor CLI: Workspace sicher im Terminal verwalten

Viele Teams beginnen in der Oberfläche: Sie erstellen Assistenten, prüfen Anrufe und passen Kampagnen manuell an. Sobald dieselben Schritte über mehrere Workspaces wiederholt, in einer Pipeline geprüft oder von einem Coding-Agenten ausgeführt werden sollen, fehlt jedoch eine reproduzierbare Schnittstelle. Genau dafür ist die Famulor CLI gedacht. Seit dem 1. Oktober 2026 steht das offizielle Kommandozeilenwerkzeug als öffentliche Vorschau bereit.

Die CLI bringt laut Famulor-Changelog vom 1. Oktober 2026 jede öffentliche REST-API-Operation als Befehl ins Terminal. Sie können damit unter anderem Assistenten, Anrufe, Kampagnen, Leads, Telefonnummern und Gesprächsverläufe verwalten. Dieser Leitfaden zeigt die Einrichtung, einen kontrollierten Automationsablauf und die Grenzen, die Sie vor dem produktiven Einsatz kennen sollten.

Das Wichtigste in Kürze

• Die Famulor CLI ist eine öffentliche Vorschau der Version 0.x. Befehlsnamen können sich vor Version 1.0 noch ändern.
• Voraussetzung sind Node.js 22 oder neuer, ein Workspace-Tarif mit API Access und ein API-Schlüssel aus Settings → API & MCP.
• Interaktive Anmeldungen verwenden nach Möglichkeit den System-Schlüsselbund. In CI wird FAMULOR_API_KEY aus dem Secret Store gelesen, ohne dass die CLI den Schlüssel speichert.
• JSON, Tabellen und JSON Lines trennen menschliche Kontrolle von maschineller Weiterverarbeitung.
• --dry-run, explizite Bestätigungen, Exit-Codes und strukturierte Fehler helfen bei sicheren Abläufen. Sie ersetzen keine Berechtigungs-, Freigabe- oder Datenschutzregeln.

Die Content-Lücke: CLI ist nicht dasselbe wie API oder MCP

Famulor dokumentiert bereits den MCP-Server für AI Agents und einen Famulor.io Skill für API-Aktionen. Beide Ansätze verbinden KI-Systeme mit der Plattform. Die CLI löst jedoch ein anderes Problem.

Die CLI ersetzt diese Zugänge nicht. Sie legt eine dünne, dokumentierte Kommandozeilenschicht über die REST API. Dadurch müssen Teams für einen Export, eine Prüfung oder eine kleine Automation nicht zuerst einen eigenen API-Client schreiben. Für längere Produktintegrationen bleibt die REST API weiterhin die passende Grundlage; für Gespräche in einem KI-Client verweist die CLI-Dokumentation auf MCP.

Für wen die Famulor CLI besonders relevant ist

Die neue Oberfläche richtet sich vor allem an Teams, die kontrollierbare, wiederholbare Abläufe benötigen:

• Agenturen und White-Label-Anbieter, die mehrere Workspaces über getrennte Profile verwalten
• Voice-AI- und Operations-Teams, die Assistenten, Kampagnen oder fehlgeschlagene Anrufe regelmäßig prüfen
• Entwicklerinnen und Entwickler, die API-Abläufe zunächst im Terminal erkunden und später in Code übertragen
• DevOps- und QA-Teams, die Zustände in CI lesen, validieren oder dokumentieren
• Coding-Agent-Nutzer, die Befehle und Parameter maschinenlesbar entdecken lassen möchten

Der Nutzen ist nicht automatisch eine bestimmte Zeit- oder Kostenersparnis. Der belastbare Vorteil ist die Reproduzierbarkeit: Ein dokumentierter Befehl kann mit denselben Parametern erneut geprüft, in einem Review gelesen und anhand seines Exit-Codes ausgewertet werden.

Voraussetzungen und Installation

Die offizielle CLI-Übersicht nennt drei Voraussetzungen:

1. Node.js 22 oder neuer
2. einen Famulor-Workspace mit API Access
3. einen API-Schlüssel aus Settings → API & MCP

Installieren Sie anschließend das Paket global und prüfen Sie die Umgebung:

npm install --global famulor
famulor doctor

famulor doctor prüft laut Referenz unter anderem Node.js-Version, Anmeldung, Host, Netzwerkverbindung und API Access. Die CLI ist derzeit eine öffentliche Vorschau. Planen Sie deshalb Updates bewusst ein und fixieren Sie produktive Pipeline-Schritte nicht auf undokumentierte Annahmen. Das gleiche Installationskommando mit @latest aktualisiert das Werkzeug.

Interaktiv anmelden

Erstellen Sie im Famulor-Dashboard einen Schlüssel mit den benötigten Scopes und führen Sie dann aus:

famulor auth login
famulor auth whoami
famulor list-assistants --output table

Die Eingabe bleibt verborgen. Nach der dokumentierten Authentifizierungslogik wird der Schlüssel vor dem Speichern gegen die API geprüft. Auf macOS nutzt die CLI Keychain, unter Windows Credential Manager und unter Linux einen Secret Service wie GNOME Keyring oder KWallet. Ist kein Schlüsselbund verfügbar, weist die CLI auf eine Datei mit Nur-Eigentümer-Rechten unter ~/.config/famulor aus.

Diese Speicherung ist ein technischer Schutz, aber keine Berechtigungsstrategie. Erstellen Sie getrennte Schlüssel für getrennte Zwecke, vergeben Sie nur benötigte Scopes und widerrufen Sie einen Schlüssel im Dashboard, wenn er nicht mehr verwendet werden soll. famulor auth logout entfernt lediglich die lokale Kopie.

Mehrere Workspaces sauber trennen

Ein API-Schlüssel gehört laut Dokumentation genau zu einem Workspace. Agenturen sollten deshalb pro Workspace ein Profil speichern, statt Schlüssel in Skripten auszutauschen:

famulor auth login --profile kunde-a
famulor auth login --profile kunde-b
famulor auth status

famulor list-assistants --profile kunde-a --output table

Mit famulor auth switch kunde-a wird ein Profil zum Standard; --profile überschreibt es nur für einen Aufruf. FAMULOR_PROFILE gilt für eine ganze Shell-Sitzung. White-Label-Betreiber können bei der Anmeldung zusätzlich ihre Domain als --base-url speichern.

Ein Profil ist keine Mandantenfreigabe. Kontrollieren Sie vor schreibenden Befehlen mit famulor auth whoami, welcher Workspace, Schlüsselname und welche Scopes aktiv sind. Gerade bei gleich benannten Assistenten verhindert diese kurze Prüfung Änderungen im falschen Workspace.

Befehle finden, ohne die API auswendig zu kennen

Die CLI bildet den Operation-Identifier der API in Kebab Case ab. Der API-Vorgang createCall wird beispielsweise zu famulor create-call. Die Dokumentation zu Befehlen und Ausgabe bietet mehrere Suchwege:

famulor --help
famulor calls
famulor commands recording
famulor get-call-recording --help

Parameter im API-Pfad werden zu Argumenten, Query- und Body-Felder zu Optionen. Die CLI prüft Typen, erlaubte Werte und Pflichtfelder, bevor eine Anfrage gesendet wird. Komplexere Request Bodies können aus JSON-Dateien oder stdin gelesen werden; Textwerte mit einem führenden @ kommen aus einer Datei.

famulor create-assistant --input assistant.json --dry-run
famulor update-assistant <assistant-id> --name "Front desk" --dry-run
famulor list-calls --status completed --limit 20 --output table

Ein Dry Run sendet nichts. Er zeigt Methode, URL, Header und Body und verbirgt dabei den API-Schlüssel. Prüfen Sie trotzdem, ob der Body personenbezogene oder vertrauliche Inhalte enthält, bevor Sie die Ausgabe in ein Ticket oder Log kopieren.

Ausgabe für Menschen und Automationen

Die Famulor CLI unterstützt drei dokumentierte Formate:

Mit --all folgt die CLI der Pagination. Bei JSONL werden Einträge ausgegeben, sobald eine Seite verfügbar ist. Fortschritt und Hinweise gehen an stderr; Daten bleiben auf stdout. Dadurch kann eine Pipeline die Datenausgabe verarbeiten, ohne Statusmeldungen als Datensätze zu interpretieren.

famulor list-assistants --all --output jsonl \
  | jq -r '.id + "\t" + .name'

Verarbeiten Sie große Listen bewusst. --all kann deutlich mehr personenbezogene oder betriebliche Daten liefern als eine einzelne Seite. Speichern Sie Exporte nur dort, wo Aufbewahrung, Zugriff und Löschung geregelt sind.

Sichere Schreibvorgänge in vier Stufen

Ein robuster CLI-Ablauf trennt Lesen, Prüfen, Schreiben und Verifizieren.

1. Kontext lesen

Prüfen Sie Profil, Ressource und aktuellen Zustand. Verwenden Sie IDs statt nur Anzeigenamen, wenn mehrere gleichnamige Ressourcen möglich sind.

2. Anfrage trocken ausführen

Hängen Sie bei unterstützten API-Befehlen --dry-run an. Dokumentieren Sie die erwartete Änderung im Review, nicht den geheimen Schlüssel.

3. Änderung bewusst bestätigen

Löschungen und andere irreversible Aktionen benötigen eine Bestätigung. In CI oder bei Coding-Agenten verweigert die CLI laut Scripting-Dokumentation den Vorgang ohne --yes, statt auf eine Eingabe zu warten. Verwenden Sie --yes erst nach einer eigenen Freigabebedingung, nicht pauschal für jedes Kommando.

4. Ergebnis erneut lesen

Prüfen Sie den Zustand über einen GET- oder List-Befehl. Bei einem Timeout kann eine erstellende Anfrage die API bereits erreicht haben. Ein strukturierter Fehler kann dann may_have_executed: true enthalten. Fragen Sie den Zielzustand ab, bevor Sie denselben Create-Befehl wiederholen.

Diese vier Stufen sind wichtiger als ein möglichst kurzes Shell-Skript. Sie reduzieren Verwechslungen, machen Freigaben nachvollziehbar und vermeiden blindes Wiederholen nach unklaren Netzwerkfehlern.

CI: Geheimnisse nicht in Skripte schreiben

In nicht interaktiven Umgebungen liest die CLI FAMULOR_API_KEY aus dem Secret Store. Die Variable hat Vorrang vor gespeicherten Logins; die CLI schreibt diesen Schlüssel nicht auf die Festplatte.

- 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 }}

Das Beispiel stammt in dieser Form aus der Famulor-Dokumentation und liest nur Daten. Für Schreibvorgänge sollten Sie zusätzlich getrennte Umgebungen, eingeschränkte Scopes, geschützte Branches und eine Freigabe vorsehen. Ein Secret Store verhindert nicht, dass ein zu weit berechtigter Schlüssel einen zu großen Wirkungsbereich besitzt.

Coding-Agenten kontrolliert einsetzen

Die CLI kann ihr Befehlsschema maschinenlesbar ausgeben:

famulor commands assistant
famulor update-assistant --help --output json
famulor commands --full --output json

Außerhalb eines Terminals liefert die Befehlssuche kompaktes JSON mit Befehl, Kurzbeschreibung, Methode, Pfad und Bereich. Die Hilfe beschreibt Argumente, Typen, erlaubte Werte, Grenzen und Pflichtfelder. Damit kann ein Coding-Agent zuerst entdecken und prüfen, bevor er einen Befehl formuliert.

Ein sinnvoller Agentenauftrag begrenzt trotzdem den Handlungsspielraum:

Verwenden Sie die Famulor CLI. Lesen Sie zuerst das aktive Profil und den aktuellen Assistenten. Ermitteln Sie Befehle über famulor commands. Führen Sie jeden Schreibvorgang zunächst mit --dry-run aus. Nehmen Sie keine irreversible Aktion vor und verwenden Sie nicht --yes.

Die CLI deaktiviert in CI und Coding-Agenten Farben, Animationen und interaktive Prompts. Das macht sie maschinenfreundlich, aber nicht autonom freigabefähig. Verantwortung für Umfang, Review und erlaubte Aktionen bleibt beim betreibenden Team.

Praxisbeispiel: QA über mehrere Kunden-Workspaces

Eine Voice-AI-Agentur betreut getrennte Famulor-Workspaces. Jeden Morgen soll ein interner QA-Job fehlgeschlagene Anrufe der letzten Prüfung auflisten. Eine Mitarbeiterin entscheidet anschließend, ob ein Assistent angepasst werden muss.

Ein realistischer Ablauf:

1. Für jeden Workspace existiert ein eigenes Profil beziehungsweise ein eigenes CI-Secret mit lesenden Scopes.
2. Der Job ruft list-calls mit Statusfilter und strukturierter Ausgabe auf.
3. Die Ergebnisse werden in der internen, zugriffsgeschützten QA-Umgebung ausgewertet; sie werden nicht ungeprüft an öffentliche Logs geschrieben.
4. Eine Mitarbeiterin öffnet relevante Gesprächsdaten in Famulor und bewertet Ursache und notwendige Änderung.
5. Ein Änderungsvorschlag am Assistenten wird zuerst als --dry-run erzeugt und geprüft.
6. Nach Freigabe läuft der echte Update-Befehl mit einem getrennten, passend berechtigten Schlüssel.
7. Abschließend liest die Pipeline den Assistenten erneut und dokumentiert den erreichten Zustand.

Das Beispiel ist kein gemessenes Kundenergebnis. Es zeigt die Trennung von Beobachtung, fachlicher Entscheidung und technischer Änderung. Automatisiert wird der wiederholbare Transport; die Qualitätsentscheidung bleibt bewusst überprüfbar.

Fehler, Exit-Codes und Wiederholungen

Skripte sollten nicht nach Textfragmenten suchen. Die CLI dokumentiert feste Exit-Codes: 0 für Erfolg, 1 für API- oder Netzwerkfehler, 2 für Nutzungsfehler, 3 für Anmeldung oder Berechtigung, 4 für nicht gefunden und 5 für abgebrochene Bestätigung.

Wenn stderr kein Terminal ist, bleibt stdout bei Fehlern leer; die letzte stderr-Zeile enthält einen JSON-Fehler. Dadurch können Pipelines Fehlercode, HTTP-Status und gegebenenfalls retry_after oder may_have_executed gezielt auswerten.

Rate Limits werden innerhalb des dokumentierten Rahmens automatisch wiederholt. Erstellende Anfragen werden nach einem Timeout oder Nutzungslimit gerade nicht automatisch erneut gesendet, damit etwa ein Anruf nicht doppelt ausgelöst wird. Ihre Pipeline muss diese Unterscheidung beibehalten.

Telefonie, Aufzeichnungen und Datenschutz

Die CLI ändert nicht die Regeln des zugrunde liegenden Workspaces. Wenn ein Befehl einen Anruf startet, eine Aufzeichnung lädt oder Gesprächsdaten exportiert, gelten weiterhin Ihre Telefonie-, Einwilligungs-, Aufbewahrungs- und Zugriffsregeln.

• Testen Sie ausgehende Anrufe nur mit zulässigen Zielnummern, Zeiten und Einwilligungsgrundlagen.
• Behandeln Sie Transkripte, Aufzeichnungen, Telefonnummern und Lead-Daten als personenbezogene oder vertrauliche Daten, wo dies zutrifft.
• Schreiben Sie API-Schlüssel nicht in Repositories, Shell-Historien, Dry-Run-Artefakte oder Chatverläufe.
• Begrenzen Sie Scopes und trennen Sie lesende QA-Jobs von schreibenden Produktionsjobs.
• Prüfen Sie Logs und Exporte auf angemessene Aufbewahrung und Löschung.

Aus Keychain-Speicherung, Preview-Sicherungen oder EU-Betrieb folgt keine pauschale Compliance-Zusage für Ihren konkreten Prozess. Die organisatorische und rechtliche Bewertung bleibt vom Einsatzfall abhängig.

Testmatrix vor dem produktiven Einsatz

Führen Sie die Tests zunächst in einem begrenzten Workspace mit nicht produktiven Ressourcen durch. Eine erfolgreiche Syntaxprüfung beweist nur, dass eine Anfrage formal gültig ist; sie bewertet nicht, ob die Änderung fachlich sinnvoll ist.

Häufige Fragen

Ist die Famulor CLI stabil für Produktionspipelines?

Sie ist am 1. Oktober 2026 als öffentliche Vorschau in Version 0.x gestartet. Befehlsnamen können sich vor 1.0 ändern; ein umbenannter Befehl bleibt laut Dokumentation mindestens eine Minor-Version funktionsfähig. Prüfen und versionieren Sie Updates bewusst.

Brauche ich einen neuen API-Schlüssel?

Die CLI verwendet dieselben Workspace-API-Schlüssel wie die REST API. Für einen klar begrenzten Workflow ist ein eigener Schlüssel mit nur den benötigten Scopes dennoch sinnvoll.

Kann ich die CLI für mehrere Kunden-Workspaces verwenden?

Ja. Pro Workspace wird ein Profil gespeichert. Wechseln Sie bewusst mit auth switch, --profile oder FAMULOR_PROFILE und prüfen Sie den Kontext vor Schreibvorgängen mit auth whoami.

Was ist für einen KI-Client besser: CLI oder MCP?

Für konversationelle Arbeit in einem unterstützten KI-Client empfiehlt die Famulor-Dokumentation MCP. Die CLI passt besser zu Shell-Skripten, CI und Coding-Agenten, die deterministische Befehle und strukturierte Ausgabe benötigen.

Verhindert --dry-run jede Fehlkonfiguration?

Nein. Es sendet die Anfrage nicht und macht deren technischen Aufbau prüfbar. Ob Ziel-Workspace, Daten, Berechtigungen und fachliche Änderung richtig sind, müssen Sie separat kontrollieren.

Fazit: Automatisieren Sie den Ablauf, nicht die Verantwortung

Die Famulor CLI schließt die Lücke zwischen visueller Bedienung und einem eigenen API-Client. Profile, typisierte Optionen, strukturierte Ausgabe, Dry Runs, Exit-Codes und maschinenlesbare Hilfen schaffen eine gute Grundlage für wiederholbare Operations- und Entwicklungsabläufe.

Beginnen Sie lesend, grenzen Sie Scopes ein und machen Sie aus jedem Schreibvorgang einen überprüfbaren Ablauf: Kontext lesen, Dry Run prüfen, gezielt freigeben, Zustand verifizieren. So wird die Kommandozeile nicht nur schnell, sondern kontrollierbar.

Über die Autorin

Sarah Müller schreibt bei Famulor über Voice-AI-Produkte, Integrationen und die sichere Einführung automatisierter Kundenprozesse.