CLI y herramientas

Boost tiene herramientas propias para que personas y agentes de IA puedan mirar, probar y operar sin riesgo. Todas comparten estas reglas:

El inicio de sesión lo hace la persona, siempre en el navegador. Ninguna herramienta pide correo, llave ni contraseña en la terminal: abren Boost y la persona aprueba o entra ahí. Ningún agente pide ni escribe contraseñas o llaves, y las herramientas nunca las imprimen.
Leer es libre; escribir es un simulacro hasta que se antepone la palabra confirmo. Sin ella, un comando que escribe solo muestra lo que haría. Cada escritura real la aprueba una persona.
Nunca se muestran secretos ni datos personales: los archivos de credenciales no se leen ni se imprimen, y teléfonos, correos y llaves salen tapados en pantalla.
La ayuda está en la propia herramienta (ayuda) y es la referencia al día; esta página resume para qué sirve cada una.

La CLI de la web

En el Monorepo: npm run -s web -- <comando>. Abre la web de Boost como la ve un usuario, con una sesión real, y reporta lo que pasó.

Comando	Qué hace
`login`	Abre Boost en una ventana de Chrome y la persona entra ahí, como siempre. La terminal no pide nada. Queda guardada en su computadora solo la sesión de la web, con permisos restringidos. Una cuenta de plataforma solo se guarda si se pide expresamente.
`estado`	De quién es la sesión y cuándo vence (sin mostrar nada secreto).
`salir`	Cierra la sesión y borra el archivo local.
`ver <pantalla>`	Abre una pantalla (por ejemplo `/interacciones`), toma la captura y guarda un reporte con los errores de consola, las peticiones que fallaron y el estado de los sockets. Acepta vista de teléfono, tamaño de ventana y página completa.
`humo`	La revisión rápida después de cada despliegue: que Interacciones cargue con conversaciones, que el socket conecte, que no haya errores de consola y que la pestaña de canales abra. Solo abre un chat si la sesión es de la entidad de demostración (abrirlo lo marca como leído); en otra entidad lo pide con `confirmo`.
`clic <pantalla> <selector>`	Simulacro: marca el elemento y lo captura, sin hacer clic. Con `confirmo clic …` hace el clic de verdad, después de que la persona dijo que sí.

Usa Playwright si está instalado y, si no, Chrome por sus herramientas de depuración. Las capturas y reportes quedan en una carpeta de la persona, fuera del repositorio. Sus pruebas: npm run test:web-cli.

La CLI del backend (`boost`)

En BoostAPI: yarn -s boost <área> <comando>. Es una familia de herramientas sobre un núcleo común, y sus reglas no se negocian:

Leer es consultar la base de datos dentro de una transacción de solo lectura: solo se aceptan consultas que leen, sin columnas de credenciales.
Escribir es pasar por el propio backend, con la sesión de la persona: mismos permisos, validaciones y efectos que la aplicación. Ninguna área escribe directo en una base.
confirmo va delante del área: yarn -s boost confirmo wf pausar 12. Sin él todo es simulacro, y en Claude Code cada escritura real le pide la aprobación a la persona.
Nada irreversible: no borra, nunca administra accesos (usuarios, roles, permisos, suscripciones) y guarda un respaldo antes de cambiar algo que existe.
yarn -s boost quien-soy dice con qué usuario y en qué entidad se está trabajando y cuándo vence la sesión.
boost login abre Boost en el navegador y la persona aprueba el código que aparece; dura 30 días que se renuevan al usarla. Es la única forma de entrar: ninguna herramienta pide contraseña en la terminal. Existe además una cuenta de IA de Boost: boost login --ia abre su sesión con una llave que la persona guardó antes en su computadora, sin tocar la sesión personal, y un comando la usa solo si lleva --ia. Esa cuenta no es de plataforma, así que las operaciones de plataforma (como el editor de workflows) le responden que no.

Las áreas

Área	Qué hace
`wf`	Workflows: leer, explicar, validar, simular, auditar, reportar, crear, activar y pausar; ver y repartir colas; ver y poner horarios. Es lo mismo que `yarn -s wf`.
`ops`	Operación del backend en producción: variables (ver; poner solo las de una lista blanca), despliegues, registros y errores con los datos personales tapados, y la CLI de AWS con llaves de un archivo que nunca se imprimen.
`db`	`db leer "<consulta>"`: la base de Boost en solo lectura, sin secretos ni `*`, con tope de tiempo y la pantalla tapada.
`canales`	Los canales de Meta y el correo: cuentas de canal de una entidad con sus interruptores, a dónde entrega Meta los mensajes, si una página y su Instagram tienen la app suscrita, qué ve Meta con el acceso de un número, plantillas entre cuentas de WhatsApp, multimedia y buzones.
`errores`	Los errores de producción por código: los más frecuentes, dónde y cuándo ocurrió uno y su ficha (qué significa y qué hacer). Solo lectura.
`authz`	Roles y permisos, para entenderlos: qué rol tiene cada quien, qué puede hacer y por qué, matrices y comparaciones entre entidades. Solo lectura, y responde igual que el servidor (una prueba lo compara).
`comms`	Lecturas de la puesta en marcha de los canales. No describe el estado de hoy: para operar los canales se usa `canales`.

Comandos que más se usan

Para	Comando
Saber si un cambio ya está en producción	`ops deploys` lista los últimos despliegues del backend y cuál está vivo; `ops deploys esperar --commit <sha>` espera a que ese commit quede vivo y termina con un código que se puede encadenar.
Ver qué falla	`ops errores --horas 24` agrupa errores y avisos por mensaje; `--texto` lo acota a una ruta, un módulo o un código. `ops logs "<texto>"` busca en los registros.
Ver los canales de una entidad	`canales cuentas --entidad N`: cada número, página o buzón con su estado, sus interruptores y avisos en palabras (workflows apagados en el número, registro de WhatsApp a medias con su siguiente paso, envíos fallidos del día).
Ver si los workflows de una entidad están encendidos	`canales workflows --entidad N`: encendidos, apagados o mixtos, número por número, y si la entidad tiene su usuario de workflows. No escribe: el interruptor se mueve en Configuraciones, solo plataforma.
Ver el reparto de un workflow	`wf cola <id>`: quién está en cada cola por turnos, cuántos turnos tiene cada persona y a quién le toca.
Repartir chats sin vendedor	`wf repartir <id>` muestra cuántos y a quién; con `confirmo` los asigna con la cola del workflow, en orden de llegada. Solo asigna: no le escribe a nadie.
Ver o poner horarios de atención	`wf horario ver --entidad N` muestra el horario hábil de cada persona y agencia; `wf horario poner …` lo cambia (reemplaza la semana entera) y es lo que consulta la acción de revisar el horario.
Revisar cómo van los workflows	`wf reporte --entidad N`: semáforo, errores por causa, plantillas, embudo, esperas y costo estimado, sin datos de clientes. `wf traza <ejecución>` sigue una ejecución paso a paso.

Desde el Monorepo se usa igual con npm run -s boost -- <área> <comando>: busca la copia de BoostAPI de al lado y le pasa los argumentos. Ahí, confirmo y login --ia solo corren en la terminal de la persona (un agente recibe el simulacro); login a secas abre Boost en el navegador para que la persona apruebe.

La referencia completa está en docs/cli/ de BoostAPI: las reglas en su README, la operación de producción en operacion-prod.md y los casos resueltos en casos.md.

Casos de operación

docs/cli/casos.md de BoostAPI reúne problemas reales de producción, cada uno con su síntoma, los comandos para diagnosticarlo, la causa, el arreglo y qué no hacer. Por ejemplo: un workflow que “no funciona” y no tiene ejecuciones (casi siempre los workflows están apagados en ese número), una cuenta de Instagram que recibe pero no envía, el alta de páginas que falla por la configuración de Meta, un código de verificación que no llega por llamada, o una prueba en producción que falla igual porque el despliegue todavía no terminó.

Las lecciones que valen para todo:

Mirar los registros antes de tocar código: casi siempre dicen la causa.
Mirar entidad por entidad: lo que pasa en una no prueba nada de las demás.
Al cambiar un valor por defecto, buscar quién más lo lee o lo valida.
Esperar el despliegue antes de probar un arreglo en producción.
Distinguir la configuración de Meta del código: un rechazo de Meta por configuración no se arregla en Boost.
Simulacro primero, y el comando real lo aprueba una persona.

Workflows

yarn -s wf (equivalente a yarn -s boost wf): leer, explicar, validar con el validador real del motor, simular quién atendería un mensaje, crear en borrador, activar, pausar, cambiar la prioridad (el número más bajo se evalúa primero), probar sobre el chat de quien prueba y cancelar una ejecución, siempre con simulacro y confirmo. No hay comando para borrar, a propósito.
yarn docs:workflows:catalog: genera desde el código el catálogo exacto de disparadores, acciones, opciones y variables. Es el único documento de workflows que no puede desincronizarse.
La documentación del motor (misión, invariantes, proceso, manual para quien arma flujos) vive en docs/workflows/ de BoostAPI.

Rationale: el porqué del código

Cada repositorio guarda en .rationale/ sus decisiones, restricciones, riesgos y excepciones como registros versionados con el código. Los agentes los consultan antes de cambiar algo (qué decisión gobierna este archivo, qué no se puede romper) y registran lo nuevo al terminar. Una persona puede seguirlo en vivo con rationale ui y fijar las reglas que ningún agente puede reemplazar con rationale pin.

Codebase Memory: el mapa del código

Un índice del código como grafo (quién llama a quién, dónde se define cada cosa) que los agentes usan para ubicar un símbolo, sus llamadas y sus archivos antes de leerlos.

Skills de los agentes

Procedimientos guardados que un agente carga cuando el pedido lo amerita. Entre ellos:

Workflows (en BoostAPI): crear un workflow desde un pedido en lenguaje natural, cambiar uno que ya existe, leerlo y explicarlo, revisar cómo van en producción y depurarlos, todo con la CLI. Los acompañan tres subagentes: uno que diseña y simula la especificación, uno que la revisa como segunda opinión independiente y uno que lee y audita lo que ya corre.
Tickets: subir y actualizar tickets del espacio de Tickets desde la terminal.
Operación (operar-prod y operar-canales, en los dos repositorios): revisar variables, despliegues, registros, errores y la base de producción, y los canales de Meta y de correo, siempre leyendo primero y con confirmo para lo que escribe.
Rationale: preparar un cambio, explicar un código raro y registrar lo aprendido.
Web (en el Monorepo): las convenciones de Next.js, React y el sistema de diseño.

Viven en .claude/skills/ y .agents/skills/ de cada repositorio; los subagentes, en .claude/agents/ de BoostAPI.