Famulor CLI : gérez votre espace de travail en toute sécurité depuis le terminal

De nombreuses équipes commencent par l'interface utilisateur : elles créent des assistants, examinent des appels et ajustent des campagnes manuellement. Dès lors que ces mêmes étapes doivent être répétées sur plusieurs espaces de travail, vérifiées dans un pipeline ou exécutées par un agent de codage, les équipes ont besoin d'une interface reproductible. C'est précisément l'objectif de la CLI Famulor, l'outil en ligne de commande officiel lancé en version bêta publique le 1er octobre 2026.

Selon le journal des modifications Famulor du 1er octobre 2026, la CLI expose chaque opération de l'API REST publique sous forme de commande terminal. Elle permet de gérer les assistants, les appels, les campagnes, les prospects, les numéros de téléphone et l'historique des appels. Ce guide détaille la configuration, un flux d'automatisation contrôlé et les limites à comprendre avant toute utilisation en production.

Points clés

• La CLI Famulor est en version bêta publique 0.x. Les noms des commandes sont susceptibles d'évoluer avant la version 1.0.
• Elle nécessite Node.js 22 ou une version ultérieure, un plan d'espace de travail avec accès API, ainsi qu'une clé API générée depuis Paramètres → API & MCP.
• Les connexions interactives utilisent le trousseau système lorsque celui-ci est disponible. En CI, FAMULOR_API_KEY est lu depuis le coffre-fort de secrets sans que la CLI ne l'enregistre.
• Les formats JSON, tableau et JSON Lines permettent de distinguer l'examen humain du traitement machine.
• --dry-run, les confirmations explicites, les codes de sortie et les erreurs structurées favorisent des flux de travail plus sûrs. Ils ne remplacent toutefois pas les permissions, les approbations ou les règles de protection des données.

Le fossé fonctionnel : la CLI n'est ni l'API ni le MCP

Famulor propose déjà le serveur MCP pour les agents IA et une compétence Famulor.io pour les actions API. Ces deux approches connectent les systèmes d'IA à la plateforme, mais la CLI répond à un besoin différent.

La CLI ne remplace pas ces options. Elle ajoute une couche de ligne de commande documentée au-dessus de l'API REST. Les équipes peuvent exporter des données, valider un état ou construire une petite automatisation sans avoir à écrire un client API complet. L'API REST demeure la base recommandée pour une intégration produit complète ; pour le travail conversationnel au sein d'un client IA, la documentation de la CLI renvoie vers le MCP.

À qui s'adresse la CLI Famulor ?

Cette nouvelle interface est particulièrement pertinente pour les équipes ayant besoin d'opérations contrôlées et reproductibles :

• Agences et fournisseurs en marque blanche gérant plusieurs espaces de travail via des profils distincts
• Équipes d'IA vocale et opérationnelles vérifiant régulièrement les assistants, les campagnes ou les appels ayant échoué
• Développeurs explorant le comportement de l'API dans le terminal avant de l'intégrer dans le code applicatif
• Équipes DevOps et QA lisant, validant ou documentant l'état en CI
• Utilisateurs d'agents de codage ayant besoin de découvrir des commandes lisibles par machine et des schémas de paramètres

L'avantage n'est pas une économie automatique de temps ou d'argent. L'avantage défendable est la reproductibilité : une commande documentée peut être examinée, répétée avec les mêmes paramètres et évaluée via son code de sortie.

Configuration requise et installation

L'aperçu officiel de la CLI liste trois prérequis :

1. Node.js 22 ou plus récent
2. un plan d'espace de travail Famulor avec accès API
3. une clé API issue de Paramètres → API & MCP

Installez le paquet globalement et vérifiez l'environnement :

npm install --global famulor
famulor doctor

La documentation indique que famulor doctor vérifie la version de Node.js, la connexion enregistrée, l'hôte, la connexion réseau et l'accès API. Comme la CLI est actuellement en version bêta publique, planifiez vos mises à jour avec précaution et ne construisez pas de pipelines de production basés sur des hypothèses non documentées. L'exécution de la commande d'installation avec @latest met à jour l'outil.

Connexion interactive

Créez une clé avec les portées requises dans le tableau de bord Famulor, puis exécutez :

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

La saisie reste masquée. Selon le flux d'authentification documenté, la clé est vérifiée auprès de l'API avant d'être enregistrée. La CLI utilise le trousseau (Keychain) sur macOS, le gestionnaire d'identification sur Windows et un service de secrets tel que GNOME Keyring ou KWallet sur Linux. Si aucun trousseau n'est disponible, elle utilise un fichier de repli accessible uniquement par le propriétaire sous ~/.config/famulor.

Ce stockage est un contrôle technique, pas une stratégie d'autorisation. Créez des clés distinctes pour des usages distincts, n'accordez que les portées nécessaires et révoquez une clé dans le tableau de bord lorsqu'elle n'est plus utile. famulor auth logout supprime uniquement la copie locale.

Maintenir la séparation des espaces de travail

Une clé API appartient à un seul espace de travail. Les agences doivent donc enregistrer un profil par espace de travail plutôt que d'échanger les clés au sein des 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 définit un profil par défaut, tandis que --profile le remplace pour une seule commande. FAMULOR_PROFILE s'applique à toute une session shell. Les opérateurs en marque blanche peuvent également enregistrer leur domaine avec --base-url lors de la connexion.

Un profil ne constitue pas une approbation de locataire. Avant toute commande d'écriture, utilisez famulor auth whoami pour confirmer l'espace de travail actif, le nom de la clé et les portées. Cette vérification rapide permet d'éviter d'effectuer des modifications sur le mauvais espace de travail lorsque les assistants portent des noms similaires.

Découvrir les commandes sans mémoriser l'API

La CLI convertit l'ID d'opération API en format kebab-case. L'opération API createCall devient famulor create-call. La documentation des commandes et des sorties propose plusieurs chemins de découverte :

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

Les paramètres de chemin API deviennent des arguments ; les champs de requête et de corps deviennent des options. La CLI vérifie les types, les valeurs autorisées et les champs requis avant d'envoyer une requête. Les corps de requête complexes peuvent provenir de fichiers JSON ou de l'entrée standard (stdin), et les valeurs textuelles commençant par @ peuvent être lues depuis un fichier.

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

Une exécution à blanc (dry run) n'envoie rien. Elle affiche la méthode, l'URL, les en-têtes et le corps tout en masquant la clé API. Le corps peut toujours contenir des informations personnelles ou confidentielles, examinez-le donc avant de copier la sortie dans un ticket ou un journal.

Sorties pour les humains et l'automatisation

La CLI Famulor prend en charge trois formats documentés :

--all suit la pagination. Avec JSONL, les enregistrements sont imprimés au fur et à mesure de l'arrivée de chaque page. La progression et les messages sont envoyés vers stderr tandis que les données restent sur stdout, évitant ainsi que les pipelines ne confondent les messages d'état avec des enregistrements.

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

Utilisez les exportations massives de manière intentionnelle. --all peut renvoyer nettement plus de données personnelles ou opérationnelles qu'une seule page. Ne stockez les exportations que là où la rétention, l'accès et la suppression sont régis.

Quatre étapes pour des écritures plus sûres

Un flux de travail CLI robuste sépare la lecture, l'examen, l'écriture et la vérification.

1. Lire le contexte

Vérifiez le profil, la ressource et l'état actuel. Utilisez des ID plutôt que de simples noms d'affichage lorsque des doublons sont possibles.

2. Prévisualiser la requête

Ajoutez --dry-run aux commandes API prises en charge. Enregistrez le changement attendu dans un examen, jamais la clé secrète.

3. Approuver le changement délibérément

Les suppressions et autres actions irréversibles nécessitent une confirmation. Dans les contextes de CI et d'agents de codage, la CLI refuse de procéder sans --yes au lieu d'attendre une saisie, conformément à la documentation de scriptage. Utilisez --yes uniquement après votre propre condition d'approbation, et non comme une option par défaut.

4. Lire l'état résultant

Vérifiez via une commande GET ou list. Après un délai d'attente, une requête de création peut déjà avoir atteint l'API. Une erreur structurée peut alors inclure may_have_executed: true. Interrogez l'état cible avant de répéter la même commande de création.

Ces quatre étapes sont plus importantes que la production du script shell le plus court. Elles réduisent les erreurs de contexte, rendent l'approbation visible et évitent les tentatives aveugles après des échecs réseau ambigus.

CI : garder les secrets hors des scripts

Dans les environnements non interactifs, la CLI lit FAMULOR_API_KEY depuis le coffre-fort de secrets. La variable a priorité sur les connexions enregistrées, et la CLI n'écrit pas cette clé sur le disque.

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

Cet exemple en lecture seule suit la documentation Famulor. Pour les écritures, ajoutez des environnements séparés, des portées restreintes, des branches protégées et une étape d'approbation. Un coffre-fort de secrets n'empêche pas une clé trop large d'avoir un impact trop large.

Utiliser des agents de codage avec des limites explicites

La CLI peut exposer son schéma de commande sous une forme lisible par machine :

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

En dehors d'un terminal, la recherche de commande renvoie un JSON compact avec la commande, le résumé, la méthode, le chemin et la zone. La sortie d'aide décrit les arguments, les types, les valeurs autorisées, les limites et les champs requis. Un agent de codage peut découvrir et inspecter avant de construire une commande.

Une instruction d'agent utile restreint toujours l'espace d'action :

Utilisez la CLI Famulor. Lisez d'abord le profil actif et l'assistant actuel. Découvrez les commandes avec famulor commands. Exécutez chaque écriture avec --dry-run d'abord. N'effectuez pas d'action irréversible et n'utilisez pas --yes.

La CLI désactive les couleurs, l'animation et les invites interactives en CI et pour les agents de codage. Cela la rend conviviale pour la machine, sans pour autant s'auto-autoriser. L'équipe opérationnelle reste responsable de la portée, de l'examen et des actions autorisées.

Exemple pratique : QA sur plusieurs espaces de travail clients

Une agence d'IA vocale gère des espaces de travail Famulor distincts. Chaque matin, un travail de QA interne doit lister les appels ayant échoué depuis l'examen précédent. Un membre de l'équipe décide ensuite si un assistant nécessite une modification.

Un flux de travail réaliste :

1. Chaque espace de travail possède son propre profil ou secret CI avec des portées de lecture.
2. Le travail appelle list-calls avec un filtre de statut et une sortie structurée.
3. Les résultats sont traités dans un environnement de QA à accès contrôlé, et non copiés aveuglément dans des journaux publics.
4. Un membre de l'équipe examine les données de conversation pertinentes dans Famulor et évalue la cause et le changement nécessaire.
5. Une mise à jour d'assistant proposée est générée sous forme de --dry-run et examinée.
6. Après approbation, la mise à jour réelle est exécutée avec une clé séparée, dotée des portées appropriées.
7. Le pipeline lit à nouveau l'assistant et enregistre l'état résultant.

Il s'agit d'un flux de travail illustratif, et non d'un résultat client mesuré. Il sépare l'observation, le jugement professionnel et la modification technique. Le transport reproductible est automatisé tandis que la décision de qualité reste soumise à examen.

Erreurs, codes de sortie et tentatives

Les scripts ne doivent pas rechercher des fragments de texte lisibles par l'humain. La CLI documente des codes de sortie fixes : 0 pour le succès, 1 pour les erreurs d'API ou réseau, 2 pour les erreurs d'utilisation, 3 pour la connexion ou l'autorisation, 4 pour les éléments non trouvés et 5 pour une confirmation annulée.

Lorsque stderr n'est pas un terminal, stdout reste vide en cas d'échec et la dernière ligne de stderr contient une erreur JSON. Les pipelines peuvent inspecter le code d'erreur, le statut HTTP et, le cas échéant, retry_after ou may_have_executed.

Les limites de débit sont gérées par des tentatives selon les règles documentées. Les requêtes de création ne sont pas automatiquement répétées après un délai d'attente ou une limite d'utilisation, spécifiquement pour éviter une action telle que passer deux fois le même appel. Votre pipeline doit préserver cette distinction.

Téléphonie, enregistrements et protection des données

La CLI ne modifie pas les règles de l'espace de travail sous-jacent. Si une commande lance un appel, télécharge un enregistrement ou exporte des données de conversation, vos règles de téléphonie, de consentement, de rétention et d'accès s'appliquent toujours.

• Testez les appels sortants uniquement avec des numéros cibles, des horaires et une base de consentement autorisés.
• Traitez les transcriptions, enregistrements, numéros de téléphone et données de prospects comme des données personnelles ou confidentielles le cas échéant.
• Ne placez jamais de clés API dans des dépôts, l'historique shell, les artefacts d'exécution à blanc ou les transcriptions de chat.
• Restreignez les portées et séparez les travaux de QA en lecture seule des écritures en production.
• Appliquez des règles de rétention et de suppression appropriées aux journaux et aux exportations.

Le stockage dans le trousseau, les sauvegardes de prévisualisation ou les opérations dans l'UE ne créent pas de garantie de conformité globale pour votre processus. L'évaluation juridique et organisationnelle dépend du cas d'utilisation.

Matrice de test avant la production

Exécutez ces tests d'abord dans un espace de travail limité avec des ressources hors production. Une syntaxe valide prouve seulement qu'une requête est structurellement acceptable ; elle ne prouve pas que le changement métier est approprié.

Questions fréquentes

La CLI Famulor est-elle stable pour les pipelines de production ?

Elle a été lancée le 1er octobre 2026 en version bêta publique 0.x. Les noms des commandes peuvent changer avant la 1.0 ; une commande renommée reste fonctionnelle pendant au moins une version mineure selon la documentation. Examinez et mettez à jour les versions avec précaution.

Ai-je besoin d'une nouvelle clé API ?

La CLI utilise les mêmes clés API d'espace de travail que l'API REST. Une clé séparée avec uniquement les portées requises reste judicieuse pour un flux de travail étroitement défini.

Puis-je utiliser la CLI pour plusieurs espaces de travail clients ?

Oui. Enregistrez un profil par espace de travail. Changez délibérément via auth switch, --profile ou FAMULOR_PROFILE, et confirmez le contexte avec auth whoami avant les écritures.

Quel est le meilleur choix pour un client IA : CLI ou MCP ?

Pour le travail conversationnel dans un client IA pris en charge, Famulor recommande le MCP. La CLI est mieux adaptée aux scripts shell, à la CI et aux agents de codage qui nécessitent des commandes déterministes et une sortie structurée.

Est-ce que --dry-run empêche toute mauvaise configuration ?

Non. Elle n'envoie rien et rend la requête technique examinable. Vous devez toujours vérifier l'espace de travail cible, les données, les permissions et l'intention métier.

Conclusion : automatisez le flux de travail, pas la responsabilité

La CLI Famulor comble le fossé entre l'administration visuelle et un client API personnalisé. Les profils, les options typées, la sortie structurée, les exécutions à blanc, les codes de sortie et l'aide lisible par machine fournissent une base solide pour des opérations reproductibles et des flux de travail de développement.

Commencez en lecture seule, restreignez les portées et rendez chaque écriture examinable : lisez le contexte, inspectez l'exécution à blanc, approuvez délibérément et vérifiez l'état résultant. Cela rend la ligne de commande non seulement rapide, mais contrôlable.

À propos de l'auteur

Sarah Müller écrit sur les produits d'IA vocale, les intégrations et l'adoption sécurisée des flux de travail clients automatisés chez Famulor.