Famulor CLI: Beheer je werkomgeving veilig via de terminal

Veel teams beginnen in de gebruikersinterface: ze maken assistenten aan, beoordelen gesprekken en passen campagnes handmatig aan. Zodra dezelfde stappen herhaald moeten worden in verschillende werkomgevingen, gecontroleerd moeten worden in een pipeline of uitgevoerd door een coding agent, hebben teams een reproduceerbare interface nodig. Dat is het doel van de Famulor CLI, de officiële command-line tool die op 1 oktober 2026 als publieke preview is uitgebracht.

Volgens de Famulor changelog van 1 oktober 2026 stelt de CLI elke publieke REST API-operatie beschikbaar als terminalcommando. Hiermee kun je assistenten, gesprekken, campagnes, leads, telefoonnummers en gesprekshistorie beheren. Deze gids behandelt de installatie, een gecontroleerde automatiseringsworkflow en de limieten die je moet begrijpen voordat je de tool in productie neemt.

Kernpunten

• De Famulor CLI is een publieke preview in versie 0.x. Commandonamen kunnen wijzigen vóór versie 1.0.
• Het vereist Node.js 22 of nieuwer, een werkomgeving-abonnement met API Access en een API-sleutel uit Settings → API & MCP.
• Interactieve logins maken gebruik van de systeem-keychain waar beschikbaar. In CI wordt FAMULOR_API_KEY uit de secret store gelezen zonder dat de CLI deze opslaat.
• JSON, tabel- en JSON Lines-output scheiden menselijke beoordeling van machineverwerking.
• --dry-run, expliciete bevestigingen, exit codes en gestructureerde foutmeldingen ondersteunen veiligere workflows. Ze vervangen echter geen rechten, goedkeuringsprocessen of regels voor gegevensbescherming.

Het gat in de dekking: CLI is niet hetzelfde als API of MCP

Famulor biedt al de MCP-server voor AI-agents en een Famulor.io skill voor API-acties. Beide benaderingen verbinden AI-systemen met het platform, maar de CLI lost een ander probleem op.

De CLI vervangt deze opties niet. Het voegt een gedocumenteerde command-line laag toe over de REST API. Teams kunnen data exporteren, de status valideren of een kleine automatisering bouwen zonder eerst een API-client te schrijven. De REST API blijft de juiste basis voor een volledige productintegratie; voor conversatiewerk binnen een AI-client verwijst de CLI-documentatie naar MCP.

Wie moet de Famulor CLI gebruiken?

De nieuwe interface is met name relevant voor teams die behoefte hebben aan gecontroleerde, herhaalbare operaties:

• Agentschappen en white-label providers die meerdere werkomgevingen beheren via afzonderlijke profielen
• Voice AI- en operatieteams die regelmatig assistenten, campagnes of mislukte gesprekken controleren
• Ontwikkelaars die API-gedrag in de terminal verkennen voordat ze dit in applicatiecode verwerken
• DevOps- en QA-teams die de status in CI lezen, valideren of documenteren
• Gebruikers van coding-agents die machineleesbare commando-detectie en parameterschema's nodig hebben

Het voordeel is niet een automatische besparing van tijd of geld. Het verdedigbare voordeel is reproduceerbaarheid: een gedocumenteerd commando kan worden gecontroleerd, herhaald met dezelfde parameters en geëvalueerd via de exit code.

Vereisten en installatie

Het officiële CLI-overzicht noemt drie vereisten:

1. Node.js 22 of nieuwer
2. een Famulor werkomgeving-abonnement met API Access
3. een API-sleutel uit Settings → API & MCP

Installeer het pakket wereldwijd en controleer de omgeving:

npm install --global famulor
famulor doctor

De referentie zegt dat famulor doctor de Node.js-versie, opgeslagen login, host, netwerkverbinding en API Access controleert. Omdat de CLI momenteel een publieke preview is, moet je plan-updates bewust doorvoeren en geen productie-pipelines bouwen rond ongedocumenteerde aannames. Het uitvoeren van het installatiecommando met @latest werkt de tool bij.

Interactieve login

Maak een sleutel met de vereiste scopes in het Famulor-dashboard en voer vervolgens uit:

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

De invoer blijft verborgen. Onder de gedocumenteerde authenticatiestroom wordt de sleutel gecontroleerd tegen de API voordat deze wordt opgeslagen. De CLI gebruikt Keychain op macOS, Credential Manager op Windows en een Secret Service zoals GNOME Keyring of KWallet op Linux. Als er geen keychain beschikbaar is, rapporteert het een fallback-bestand dat alleen toegankelijk is voor de eigenaar onder ~/.config/famulor.

Deze opslag is een technische controle, geen autorisatiestrategie. Maak aparte sleutels voor aparte doeleinden, verleen alleen de vereiste scopes en trek een sleutel in het dashboard in wanneer deze niet meer nodig is. famulor auth logout verwijdert alleen de lokale kopie.

Houd meerdere werkomgevingen gescheiden

Een API-sleutel hoort bij precies één werkomgeving. Agentschappen moeten daarom één profiel per werkomgeving opslaan in plaats van sleutels te wisselen in scripts:

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

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

famulor auth switch client-a maakt een profiel de standaard, terwijl --profile dit overschrijft voor één aanroep. FAMULOR_PROFILE is van toepassing op een volledige shell-sessie. White-label operators kunnen ook hun domein opslaan met --base-url tijdens het inloggen.

Een profiel is geen goedkeuring voor een tenant. Gebruik vóór schrijfcommando's famulor auth whoami om de actieve werkomgeving, sleutelnaam en scopes te bevestigen. Die korte controle helpt voorkomen dat er wijzigingen worden aangebracht in de verkeerde werkomgeving wanneer assistenten vergelijkbare namen hebben.

Commando's ontdekken zonder de API uit je hoofd te leren

De CLI zet de API-operatie-ID om naar kebab-case. De createCall API-operatie wordt famulor create-call. De documentatie voor commando's en output biedt verschillende ontdekkingspaden:

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

API-padparameters worden argumenten; query- en body-velden worden opties. De CLI controleert types, toegestane waarden en vereiste velden voordat een verzoek wordt verzonden. Complexe request bodies kunnen afkomstig zijn uit JSON-bestanden of stdin, en tekstwaarden die beginnen met @ kunnen uit een bestand worden gelezen.

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

Een dry run verstuurt niets. Het toont de methode, URL, headers en body terwijl de API-sleutel verborgen blijft. De body kan nog steeds persoonlijke of vertrouwelijke inhoud bevatten, dus controleer deze voordat je de output kopieert naar een ticket of logboek.

Output voor mensen en automatisering

De Famulor CLI ondersteunt drie gedocumenteerde formaten:

--all volgt paginering. Met JSONL worden records geprint zodra elke pagina binnenkomt. Voortgang en berichten gaan naar stderr terwijl data op stdout blijft, zodat pipelines statusberichten niet per ongeluk als records lezen.

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

Gebruik grote exports bewust. --all kan aanzienlijk meer persoonlijke of operationele data retourneren dan één pagina. Sla exports alleen op waar retentie, toegang en verwijdering gereguleerd zijn.

Vier fasen voor veiligere schrijfacties

Een robuuste CLI-workflow scheidt lezen, beoordelen, schrijven en verifiëren.

1. Lees de context

Controleer het profiel, de resource en de huidige status. Gebruik ID's in plaats van alleen weergavenamen wanneer dubbele namen mogelijk zijn.

2. Bekijk het verzoek vooraf

Voeg --dry-run toe aan ondersteunde API-commando's. Leg de verwachte wijziging vast in een beoordeling, nooit de geheime sleutel.

3. Keur de wijziging bewust goed

Verwijderingen en andere onomkeerbare acties vereisen bevestiging. In CI- en coding-agent-contexten weigert de CLI door te gaan zonder --yes in plaats van te wachten op invoer, volgens de scripting-documentatie. Gebruik --yes alleen na je eigen goedkeuringsvoorwaarde, niet als een algemene optie.

4. Lees de resulterende status

Verifieer via een GET- of list-commando. Na een time-out kan een create-verzoek de API al hebben bereikt. Een gestructureerde fout kan dan may_have_executed: true bevatten. Query de doelstatus voordat je hetzelfde create-commando herhaalt.

Deze vier fasen zijn belangrijker dan het produceren van het kortste shell-script. Ze verminderen contextfouten, maken goedkeuring zichtbaar en voorkomen blinde retries na ambigue netwerkfouten.

CI: houd geheimen uit scripts

In niet-interactieve omgevingen leest de CLI FAMULOR_API_KEY uit de secret store. De variabele krijgt voorrang op opgeslagen logins en de CLI schrijft die sleutel niet naar de schijf.

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

Dit read-only voorbeeld volgt de Famulor-documentatie. Voeg voor schrijfacties aparte omgevingen, beperkte scopes, beschermde branches en een goedkeuringsstap toe. Een secret store voorkomt niet dat een te brede sleutel een te brede impact heeft.

Gebruik coding-agents met expliciete grenzen

De CLI kan zijn commando-schema in machineleesbare vorm presenteren:

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

Buiten een terminal retourneert commando-zoekopdrachten compacte JSON met commando, samenvatting, methode, pad en gebied. Help-output beschrijft argumenten, types, toegestane waarden, limieten en vereiste velden. Een coding-agent kan ontdekken en inspecteren voordat hij een commando opbouwt.

Een nuttige agent-instructie beperkt de actieruimte:

Gebruik de Famulor CLI. Lees eerst het actieve profiel en de huidige assistent. Ontdek commando's met famulor commands. Voer elke schrijfactie eerst uit met --dry-run. Voer geen onomkeerbare actie uit en gebruik geen --yes.

De CLI schakelt kleuren, animaties en interactieve prompts uit in CI en coding-agents. Dat maakt het machinevriendelijk, niet zelf-autoriserend. Het operatieteam blijft verantwoordelijk voor scope, beoordeling en toegestane acties.

Praktijkvoorbeeld: QA over klantwerkomgevingen heen

Een Voice AI-agentschap beheert afzonderlijke Famulor-werkomgevingen. Elke ochtend moet een interne QA-taak mislukte gesprekken sinds de vorige beoordeling weergeven. Een teamlid beslist vervolgens of een assistent een wijziging nodig heeft.

Een realistische workflow:

1. Elke werkomgeving heeft zijn eigen profiel of CI-geheim met lees-scopes.
2. De taak roept list-calls aan met een statusfilter en gestructureerde output.
3. Resultaten worden verwerkt in een QA-omgeving met toegangscontrole, niet blindelings gekopieerd naar openbare logboeken.
4. Een teamlid beoordeelt relevante gespreksdata in Famulor en beoordeelt de oorzaak en de noodzakelijke wijziging.
5. Een voorgestelde assistent-update wordt gegenereerd als een --dry-run en beoordeeld.
6. Na goedkeuring wordt de echte update uitgevoerd met een aparte, passend gescoped sleutel.
7. De pipeline leest de assistent opnieuw en legt de resulterende status vast.

Dit is een illustratieve workflow, geen gemeten klantresultaat. Het scheidt observatie, professioneel oordeel en technische modificatie. Het herhaalbare transport is geautomatiseerd terwijl de kwaliteitsbeslissing beoordeelbaar blijft.

Fouten, exit codes en retries

Scripts moeten niet zoeken naar fragmenten van menselijk leesbare tekst. De CLI documenteert vaste exit codes: 0 voor succes, 1 voor API- of netwerkfouten, 2 voor gebruiks-fouten, 3 voor login of autorisatie, 4 voor niet gevonden en 5 voor een geannuleerde bevestiging.

Wanneer stderr geen terminal is, blijft stdout leeg bij een fout en bevat de laatste stderr-regel een JSON-fout. Pipelines kunnen de foutcode, HTTP-status en, indien aanwezig, retry_after of may_have_executed inspecteren.

Rate limits worden opnieuw geprobeerd binnen de gedocumenteerde regels. Create-verzoeken worden niet automatisch herhaald na een time-out of gebruikslimiet, specifiek om te voorkomen dat een actie zoals het plaatsen van hetzelfde gesprek twee keer wordt uitgevoerd. Je pipeline moet dat onderscheid bewaren.

Telefonie, opnames en gegevensbescherming

De CLI wijzigt de regels van de onderliggende werkomgeving niet. Als een commando een gesprek start, een opname downloadt of gespreksdata exporteert, blijven je regels voor telefonie, toestemming, retentie en toegang van kracht.

• Test uitgaande gesprekken alleen met toegestane doelnummers, tijden en toestemmingsbasis.
• Behandel transcripties, opnames, telefoonnummers en lead-data als persoonlijke of vertrouwelijke gegevens waar van toepassing.
• Plaats nooit API-sleutels in repositories, shell-geschiedenis, dry-run-artefacten of chat-transcripties.
• Beperk scopes en scheid read-only QA-taken van productie-schrijfacties.
• Pas passende retentie- en verwijderingsregels toe op logboeken en exports.

Keychain-opslag, preview-waarborgen of EU-operaties creëren geen algemene compliance-garantie voor je proces. De juridische en organisatorische beoordeling hangt af van de use case.

Testmatrix vóór productie

Voer deze tests eerst uit in een beperkte werkomgeving met niet-productie-resources. Geldige syntax bewijst alleen dat een verzoek structureel acceptabel is; het bewijst niet dat de zakelijke wijziging gepast is.

Veelgestelde vragen

Is de Famulor CLI stabiel voor productie-pipelines?

Het werd op 1 oktober 2026 gelanceerd als een publieke preview in versie 0.x. Commandonamen kunnen wijzigen vóór 1.0; een hernoemd commando blijft functioneel voor ten minste één minor-versie volgens de documentatie. Beoordeel en update versies bewust.

Heb ik een nieuwe API-sleutel nodig?

De CLI gebruikt dezelfde werkomgeving-API-sleutels als de REST API. Een aparte sleutel met alleen de vereiste scopes is nog steeds verstandig voor een nauw gedefinieerde workflow.

Kan ik de CLI gebruiken voor meerdere klantwerkomgevingen?

Ja. Sla één profiel per werkomgeving op. Schakel bewust via auth switch, --profile of FAMULOR_PROFILE en bevestig de context met auth whoami vóór schrijfacties.

Wat is beter voor een AI-client: CLI of MCP?

Voor conversatiewerk in een ondersteunde AI-client raadt Famulor MCP aan. De CLI is een betere match voor shell-scripts, CI en coding-agents die deterministische commando's en gestructureerde output nodig hebben.

Voorkomt --dry-run elke misconfiguratie?

Nee. Het verstuurt niets en maakt het technische verzoek beoordeelbaar. Je moet nog steeds de doelwerkomgeving, data, rechten en zakelijke intentie verifiëren.

Conclusie: automatiseer de workflow, niet de verantwoordelijkheid

De Famulor CLI dicht het gat tussen visueel beheer en een aangepaste API-client. Profielen, getypeerde opties, gestructureerde output, dry runs, exit codes en machineleesbare help bieden een sterke basis voor herhaalbare operaties en ontwikkelworkflows.

Begin read-only, beperk scopes en maak elke schrijfactie beoordeelbaar: lees de context, inspecteer de dry run, keur bewust goed en verifieer de resulterende status. Dat maakt de command line niet alleen snel, maar ook controleerbaar.

Over de auteur

Sarah Müller schrijft over Voice AI-producten, integraties en de veilige adoptie van geautomatiseerde klantworkflows bij Famulor.