Famulor CLI: gestiona tu espacio de trabajo en la terminal con seguridad

Muchos equipos comienzan en la interfaz de usuario: crean asistentes, revisan llamadas y ajustan campañas manualmente. Una vez que los mismos pasos deben repetirse en varios espacios de trabajo, comprobarse en una canalización o ejecutarse mediante un agente de codificación, los equipos necesitan una interfaz reproducible. Ese es el propósito de la CLI de Famulor, la herramienta de línea de comandos oficial lanzada como vista previa pública el 1 de octubre de 2026.

Según el registro de cambios de Famulor del 1 de octubre de 2026, la CLI expone cada operación de la API REST pública como un comando de terminal. Puede gestionar asistentes, llamadas, campañas, clientes potenciales, números de teléfono e historial de llamadas. Esta guía cubre la configuración, un flujo de trabajo de automatización controlado y los límites que debes comprender antes del uso en producción.

Puntos clave

• La CLI de Famulor es una vista previa pública en la versión 0.x. Los nombres de los comandos pueden cambiar antes de la versión 1.0.
• Requiere Node.js 22 o superior, un plan de espacio de trabajo con Acceso a la API y una clave de API desde Configuración → API y MCP.
• Los inicios de sesión interactivos utilizan el llavero del sistema cuando está disponible. En CI, FAMULOR_API_KEY se lee desde el almacén de secretos sin que la CLI lo guarde.
• La salida en JSON, tabla y JSON Lines separa la revisión humana del procesamiento automático.
• --dry-run, las confirmaciones explícitas, los códigos de salida y los errores estructurados favorecen flujos de trabajo más seguros. No sustituyen a los permisos, la aprobación ni las normas de protección de datos.

La brecha de contenido: la CLI no es lo mismo que la API o MCP

Famulor ya explica el servidor MCP para agentes de IA y una habilidad de Famulor.io para acciones de API. Ambos enfoques conectan sistemas de IA a la plataforma, pero la CLI resuelve un problema diferente.

La CLI no sustituye a estas opciones. Añade una capa de línea de comandos documentada sobre la API REST. Los equipos pueden exportar datos, validar el estado o crear una pequeña automatización sin escribir primero un cliente de API. La API REST sigue siendo la base adecuada para una integración completa del producto; para el trabajo conversacional dentro de un cliente de IA, la documentación de la CLI apunta a MCP.

¿Quién debería usar la CLI de Famulor?

La nueva interfaz es especialmente relevante para los equipos que necesitan operaciones controladas y repetibles:

• Agencias y proveedores de marca blanca que gestionan varios espacios de trabajo a través de perfiles separados
• Equipos de IA de voz y operaciones que revisan regularmente asistentes, campañas o llamadas fallidas
• Desarrolladores que exploran el comportamiento de la API en la terminal antes de integrarlo en el código de la aplicación
• Equipos de DevOps y QA que leen, validan o documentan el estado en CI
• Usuarios de agentes de codificación que necesitan descubrimiento de comandos legible por máquina y esquemas de parámetros

El beneficio no es una cantidad automática de tiempo o dinero ahorrado. La ventaja defendible es la reproducibilidad: un comando documentado puede revisarse, repetirse con los mismos parámetros y evaluarse mediante su código de salida.

Requisitos e instalación

La descripción general oficial de la CLI enumera tres requisitos:

1. Node.js 22 o superior
2. un plan de espacio de trabajo de Famulor con Acceso a la API
3. una clave de API desde Configuración → API y MCP

Instala el paquete globalmente y comprueba el entorno:

npm install --global famulor
famulor doctor

La referencia indica que famulor doctor comprueba la versión de Node.js, el inicio de sesión guardado, el host, la conexión de red y el acceso a la API. Debido a que la CLI es actualmente una vista previa pública, planifica las actualizaciones con cuidado y no construyas canalizaciones de producción basadas en suposiciones no documentadas. Ejecutar el comando de instalación con @latest actualiza la herramienta.

Inicio de sesión interactivo

Crea una clave con los alcances requeridos en el panel de Famulor y luego ejecuta:

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

La entrada permanece oculta. Bajo el flujo de autenticación documentado, la clave se verifica contra la API antes de guardarse. La CLI utiliza el Llavero en macOS, el Administrador de credenciales en Windows y un Servicio secreto como GNOME Keyring o KWallet en Linux. Si no hay ningún llavero disponible, informa de un archivo de respaldo exclusivo del propietario en ~/.config/famulor.

Este almacenamiento es un control técnico, no una estrategia de autorización. Crea claves separadas para propósitos separados, otorga solo los alcances requeridos y revoca una clave en el panel cuando ya no sea necesaria. famulor auth logout solo elimina la copia local.

Mantén separados los múltiples espacios de trabajo

Una clave de API pertenece exactamente a un espacio de trabajo. Por lo tanto, las agencias deben guardar un perfil por espacio de trabajo en lugar de intercambiar claves dentro de los 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 establece un perfil como predeterminado, mientras que --profile lo anula para una sola llamada. FAMULOR_PROFILE se aplica a toda una sesión de shell. Los operadores de marca blanca también pueden guardar su dominio con --base-url durante el inicio de sesión.

Un perfil no es una aprobación de inquilino. Antes de los comandos de escritura, utiliza famulor auth whoami para confirmar el espacio de trabajo activo, el nombre de la clave y los alcances. Esa breve comprobación ayuda a evitar cambios en el espacio de trabajo incorrecto cuando los asistentes tienen nombres similares.

Descubre comandos sin memorizar la API

La CLI convierte el ID de operación de la API a formato kebab case. La operación de API createCall se convierte en famulor create-call. La documentación de comandos y salida ofrece varias rutas de descubrimiento:

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

Los parámetros de ruta de la API se convierten en argumentos; los campos de consulta y cuerpo se convierten en opciones. La CLI comprueba los tipos, los valores permitidos y los campos obligatorios antes de enviar una solicitud. Los cuerpos de solicitud complejos pueden provenir de archivos JSON o stdin, y los valores de texto que comienzan con @ pueden leerse desde un archivo.

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

Una ejecución de prueba (dry run) no envía nada. Muestra el método, la URL, los encabezados y el cuerpo mientras oculta la clave de API. El cuerpo aún puede contener contenido personal o confidencial, así que revísalo antes de copiar la salida en un ticket o registro.

Salida para personas y automatización

La CLI de Famulor admite tres formatos documentados:

--all sigue la paginación. Con JSONL, los registros se imprimen a medida que llega cada página. El progreso y los mensajes van a stderr mientras que los datos permanecen en stdout, por lo que las canalizaciones no confunden los mensajes de estado con registros.

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

Realiza exportaciones grandes de forma intencionada. --all puede devolver sustancialmente más datos personales u operativos que una sola página. Almacena las exportaciones solo donde la retención, el acceso y la eliminación estén regulados.

Cuatro etapas para escrituras más seguras

Un flujo de trabajo sólido de CLI separa la lectura, la revisión, la escritura y la verificación.

1. Lee el contexto

Comprueba el perfil, el recurso y el estado actual. Utiliza IDs en lugar de solo nombres para mostrar cuando sean posibles nombres duplicados.

2. Previsualiza la solicitud

Añade --dry-run a los comandos de API admitidos. Registra el cambio esperado en una revisión, nunca la clave secreta.

3. Aprueba el cambio deliberadamente

Las eliminaciones y otras acciones irreversibles requieren confirmación. En contextos de CI y agentes de codificación, la CLI se niega a continuar sin --yes en lugar de esperar la entrada, según la documentación de scripting. Utiliza --yes solo después de tu propia condición de aprobación, no como una opción general.

4. Lee el estado resultante

Verifica mediante un comando GET o list. Después de un tiempo de espera, una solicitud de creación puede haber llegado ya a la API. Un error estructurado puede incluir entonces may_have_executed: true. Consulta el estado de destino antes de repetir el mismo comando de creación.

Estas cuatro etapas importan más que producir el script de shell más corto. Reducen los errores de contexto, hacen visible la aprobación y evitan reintentos a ciegas tras fallos de red ambiguos.

CI: mantén los secretos fuera de los scripts

En entornos no interactivos, la CLI lee FAMULOR_API_KEY desde el almacén de secretos. La variable tiene prioridad sobre los inicios de sesión guardados y la CLI no escribe esa clave en el disco.

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

Este ejemplo de solo lectura sigue la documentación de Famulor. Para escrituras, añade entornos separados, alcances restringidos, ramas protegidas y un paso de aprobación. Un almacén de secretos no impide que una clave demasiado amplia tenga un impacto demasiado amplio.

Usa agentes de codificación con límites explícitos

La CLI puede exponer su esquema de comandos en forma legible por máquina:

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

Fuera de una terminal, la búsqueda de comandos devuelve JSON compacto con comando, resumen, método, ruta y área. La salida de ayuda describe argumentos, tipos, valores permitidos, límites y campos obligatorios. Un agente de codificación puede descubrir e inspeccionar antes de construir un comando.

Una instrucción útil para el agente aún reduce el espacio de acción:

Usa la CLI de Famulor. Primero lee el perfil activo y el asistente actual. Descubre comandos con famulor commands. Ejecuta cada escritura con --dry-run primero. No realices una acción irreversible y no uses --yes.

La CLI desactiva los colores, la animación y las solicitudes interactivas en CI y agentes de codificación. Eso la hace amigable para las máquinas, no auto-autorizada. El equipo operativo sigue siendo responsable del alcance, la revisión y las acciones permitidas.

Ejemplo práctico: QA en espacios de trabajo de clientes

Una agencia de IA de voz opera espacios de trabajo de Famulor separados. Cada mañana, un trabajo de QA interno debe listar las llamadas fallidas desde la revisión anterior. Un miembro del equipo decide entonces si un asistente necesita un cambio.

Un flujo de trabajo realista:

1. Cada espacio de trabajo tiene su propio perfil o secreto de CI con alcances de lectura.
2. El trabajo llama a list-calls con un filtro de estado y salida estructurada.
3. Los resultados se procesan en un entorno de QA con acceso controlado, no se copian a ciegas en registros públicos.
4. Un miembro del equipo revisa los datos de conversación relevantes en Famulor y evalúa la causa y el cambio necesario.
5. Se genera una actualización propuesta del asistente como --dry-run y se revisa.
6. Tras la aprobación, la actualización real se ejecuta con una clave separada y con el alcance adecuado.
7. La canalización lee al asistente de nuevo y registra el estado resultante.

Este es un flujo de trabajo ilustrativo, no un resultado medido del cliente. Separa la observación, el juicio profesional y la modificación técnica. El transporte repetible está automatizado mientras que la decisión de calidad sigue siendo revisable.

Errores, códigos de salida y reintentos

Los scripts no deben buscar fragmentos de texto legibles por humanos. La CLI documenta códigos de salida fijos: 0 para éxito, 1 para errores de API o red, 2 para errores de uso, 3 para inicio de sesión o autorización, 4 para no encontrado y 5 para una confirmación cancelada.

Cuando stderr no es una terminal, stdout permanece vacío en caso de fallo y la última línea de stderr contiene un error JSON. Las canalizaciones pueden inspeccionar el código de error, el estado HTTP y, cuando esté presente, retry_after o may_have_executed.

Los límites de tasa se reintentan dentro de las reglas documentadas. Las solicitudes de creación no se repiten automáticamente después de un tiempo de espera o límite de uso, específicamente para evitar una acción como realizar la misma llamada dos veces. Tu canalización debe preservar esa distinción.

Telefonía, grabaciones y protección de datos

La CLI no cambia las reglas del espacio de trabajo subyacente. Si un comando inicia una llamada, descarga una grabación o exporta datos de conversación, tus reglas de telefonía, consentimiento, retención y acceso siguen siendo aplicables.

• Prueba las llamadas salientes solo con números de destino, horarios y base de consentimiento permitidos.
• Trata las transcripciones, grabaciones, números de teléfono y datos de clientes potenciales como datos personales o confidenciales cuando corresponda.
• Nunca coloques claves de API en repositorios, historial de shell, artefactos de ejecución de prueba o transcripciones de chat.
• Restringe los alcances y separa los trabajos de QA de solo lectura de las escrituras de producción.
• Aplica reglas de retención y eliminación adecuadas a los registros y exportaciones.

El almacenamiento en el llavero, las salvaguardas de vista previa o las operaciones en la UE no crean una garantía de cumplimiento general para tu proceso. La evaluación legal y organizativa depende del caso de uso.

Matriz de pruebas antes de la producción

Ejecuta estas pruebas primero en un espacio de trabajo limitado con recursos que no sean de producción. Una sintaxis válida solo demuestra que una solicitud es estructuralmente aceptable; no demuestra que el cambio de negocio sea apropiado.

Preguntas frecuentes

¿Es la CLI de Famulor estable para canalizaciones de producción?

Se lanzó el 1 de octubre de 2026 como una vista previa pública en la versión 0.x. Los nombres de los comandos pueden cambiar antes de la 1.0; un comando renombrado permanece funcional durante al menos una versión menor según la documentación. Revisa y actualiza las versiones con cuidado.

¿Necesito una nueva clave de API?

La CLI utiliza las mismas claves de API de espacio de trabajo que la API REST. Una clave separada con solo los alcances requeridos sigue siendo sensata para un flujo de trabajo definido de forma estrecha.

¿Puedo usar la CLI para varios espacios de trabajo de clientes?

Sí. Almacena un perfil por espacio de trabajo. Cambia deliberadamente a través de auth switch, --profile o FAMULOR_PROFILE, y confirma el contexto con auth whoami antes de las escrituras.

¿Qué es mejor para un cliente de IA: CLI o MCP?

Para el trabajo conversacional en un cliente de IA compatible, Famulor recomienda MCP. La CLI es una mejor opción para scripts de shell, CI y agentes de codificación que necesitan comandos deterministas y salida estructurada.

¿Evita --dry-run toda configuración incorrecta?

No. No envía nada y hace que la solicitud técnica sea revisable. Aún debes verificar el espacio de trabajo de destino, los datos, los permisos y la intención comercial.

Conclusión: automatiza el flujo de trabajo, no la responsabilidad

La CLI de Famulor cierra la brecha entre la administración visual y un cliente de API personalizado. Los perfiles, las opciones tipadas, la salida estructurada, las ejecuciones de prueba, los códigos de salida y la ayuda legible por máquina proporcionan una base sólida para operaciones repetibles y flujos de trabajo de desarrollo.

Comienza en modo de solo lectura, restringe los alcances y haz que cada escritura sea revisable: lee el contexto, inspecciona la ejecución de prueba, aprueba deliberadamente y verifica el estado resultante. Eso hace que la línea de comandos no solo sea rápida, sino controlable.

Sobre la autora

Sarah Müller escribe sobre productos de IA de voz, integraciones y la adopción segura de flujos de trabajo automatizados para clientes en Famulor.