> ## 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.

# Scripts, CI et agents de code

> Automatisez Famulor en toute sécurité : sortie exploitable, codes de sortie, confirmations, simulations et schéma des commandes pour les agents

La CLI est conçue pour être scriptée. Les données passent par stdout, les messages par stderr, et chaque échec se termine par un code de sortie non nul.

## Sûre par défaut

* **Les suppressions et les actions irréversibles demandent d'abord une confirmation.** Cela concerne les suppressions et des actions comme l'achat d'un numéro, le transfert d'un espace de travail ou la restauration d'une ancienne version. Dans un terminal, la CLI demande de confirmer. Dans les scripts, la CI et les agents de code, passez `--yes` ; sans cette option, la commande refuse de s'exécuter.
* **Simulations.** `--dry-run` affiche la requête exacte (méthode, URL, en-têtes et corps) avec la clé API masquée, et n'envoie rien.
* **Des nouvelles tentatives sans risque de doublon.** Lorsque la limite de requêtes est atteinte, la CLI attend le délai demandé par l'API, puis réessaie. Les requêtes qui créent quelque chose ne sont jamais répétées après un délai d'attente dépassé ou une limite d'utilisation : un appel n'est donc jamais passé deux fois. `--timeout` fixe le délai maximal de toute la commande, attente comprise.
* **Aucune invite sans personne pour y répondre.** En CI et au sein des agents de code, la CLI n'attend jamais de saisie.

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

## Exemples

```bash theme={null}
# Noms de tous les assistants
famulor list-assistants --all --output jsonl | jq -r '.name'

# Activer l'enregistrement pour tous les assistants
famulor list-assistants --all --output jsonl | jq -r '.id' \
  | xargs -I{} famulor update-assistant {} --recording-enabled true

# Sauvegarder tous les appels terminés
famulor list-calls --status completed --all > calls.json
```

## Codes de sortie

| Code | Signification |
| - | - |
| `0` | Succès |
| `1` | Erreur de l'API ou du réseau |
| `2` | Erreur d'utilisation, par exemple une option inconnue ou une valeur invalide |
| `3` | Non connecté, ou l'API a refusé l'identifiant ou l'autorisation |
| `4` | Introuvable |
| `5` | Annulé lors d'une demande de confirmation |

## Erreurs dans les scripts

Lorsqu'une commande échoue, stdout reste vide, de sorte qu'un échec n'est jamais lu comme des données. Lorsque stderr n'est pas un terminal, sa dernière ligne contient l'erreur en JSON (les éventuels avertissements la précèdent) :

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

`code` est le code d'erreur de l'API. Les échecs sans réponse de l'API utilisent `network_error`, `timeout`, `invalid_response`, `usage_error` ou `auth_error`. `retry_after` indique le nombre de secondes à attendre après une limite de requêtes. `may_have_executed: true` signifie qu'une requête qui crée quelque chose a peut-être atteint l'API avant l'échec de la connexion : vérifiez donc avant de réessayer.

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

## Agents de code

Les agents de code comme Claude Code, Codex et Cursor peuvent utiliser la CLI directement :

* `famulor commands <topic>` trouve les commandes. Hors d'un terminal, elle affiche du JSON compact : commande, résumé, méthode, chemin et domaine.
* `famulor <command> --help --output json` affiche le schéma complet d'une commande : arguments, options, types, valeurs autorisées, valeurs par défaut, limites, champs obligatoires et un exemple. `famulor commands --full --output json` fait de même pour toutes les commandes.
* Les couleurs, les animations et les invites se désactivent automatiquement en CI et au sein des agents de code. Les actions irréversibles nécessitent `--yes`.
* Les messages d'erreur indiquent ce qui n'a pas fonctionné et la commande à exécuter ensuite.

Une instruction courte suffit généralement, par exemple : « Utilise la CLI `famulor`. Trouve les commandes avec `famulor commands <topic>` et consulte le détail d'une commande avec `famulor <command> --help --output json`. Teste d'abord les commandes d'écriture avec `--dry-run`. »

<Tip>
  Pour un travail conversationnel au sein d'un assistant IA, le [serveur MCP](/fr/mcp/overview) est plus adapté. Il propose les mêmes fonctionnalités sous forme d'outils.
</Tip>