> ## 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 y agentes de código

> Automatiza Famulor de forma segura: salida limpia, códigos de salida, confirmaciones, simulaciones y un esquema de comandos para agentes

La CLI está pensada para usarse en scripts. Los datos van a stdout, los mensajes van a stderr y todos los errores terminan con un código de salida distinto de cero.

## Segura por defecto

* **Las eliminaciones y las acciones irreversibles piden confirmación.** Esto incluye las eliminaciones y acciones como comprar un número, transferir un espacio de trabajo o restaurar una versión anterior. En un terminal, la CLI pide confirmación. En scripts, CI y agentes de código, pasa `--yes`; sin esa opción, el comando no se ejecuta.
* **Simulaciones.** `--dry-run` imprime la solicitud exacta (método, URL, encabezados y cuerpo) con la clave de API oculta, y no envía nada.
* **Reintentos que no pueden duplicar nada.** Cuando se alcanza el límite de solicitudes, la CLI espera el tiempo que indica la API y vuelve a intentarlo. Las solicitudes que crean algo nunca se repiten tras un tiempo de espera agotado o un límite de uso, así que una llamada nunca se realiza dos veces. `--timeout` es el plazo de todo el comando, esperas incluidas.
* **Sin avisos interactivos cuando nadie puede responder.** En CI y dentro de los agentes de código, la CLI nunca se queda esperando una entrada.

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

## Ejemplos

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

# Turn on recording for every assistant
famulor list-assistants --all --output jsonl | jq -r '.id' \
  | xargs -I{} famulor update-assistant {} --recording-enabled true

# Save every completed call
famulor list-calls --status completed --all > calls.json
```

## Códigos de salida

| Código | Significado |
| - | - |
| `0` | Éxito |
| `1` | Error de la API o de red |
| `2` | Error de uso, como una opción desconocida o un valor no válido |
| `3` | No has iniciado sesión, o la API rechazó la credencial o el permiso |
| `4` | No encontrado |
| `5` | Cancelado en una solicitud de confirmación |

## Errores en scripts

Cuando un comando falla, stdout queda vacío, así que un fallo nunca se lee como datos. Cuando stderr no es un terminal, su última línea es el error en JSON (los avisos, si los hay, van antes):

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

`code` es el código de error de la API. Los fallos sin respuesta de la API usan `network_error`, `timeout`, `invalid_response`, `usage_error` o `auth_error`. `retry_after` indica los segundos que hay que esperar tras un límite de solicitudes. `may_have_executed: true` significa que una solicitud que crea algo puede haber llegado a la API antes de que fallara la conexión, así que compruébalo antes de reintentar.

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

## Agentes de código

Los agentes de código como Claude Code, Codex y Cursor pueden usar la CLI directamente:

* `famulor commands <topic>` encuentra comandos. Fuera de un terminal imprime JSON compacto: comando, resumen, método, ruta y área.
* `famulor <command> --help --output json` imprime el esquema completo de un comando: argumentos, opciones, tipos, valores permitidos, valores predeterminados, límites, campos obligatorios y un ejemplo. `famulor commands --full --output json` hace lo mismo para todos los comandos.
* Los colores, las animaciones y los avisos interactivos se desactivan automáticamente en CI y dentro de los agentes de código. Las acciones irreversibles necesitan `--yes`.
* Los mensajes de error indican qué ha fallado y qué ejecutar a continuación.

Normalmente basta con una instrucción breve, por ejemplo: «Usa la CLI `famulor`. Busca comandos con `famulor commands <topic>` y consulta los detalles de uno con `famulor <command> --help --output json`. Prueba primero con `--dry-run` los comandos que escriben datos».

<Tip>
  Para trabajar de forma conversacional dentro de un asistente de IA, el [servidor MCP](/es/mcp/overview) es la mejor opción. Ofrece las mismas funciones en forma de herramientas.
</Tip>