feastalytics/cli

Feast CLI

Impulsa la plataforma Feastalytics desde la terminal. El CLI feast expone la misma superficie de herramientas que el agente AI interno de la aplicación (campañas, automatizaciones, ofertas, embudos, programa de miembros) como comandos simples que interactúan con la API de producción como el usuario autenticado.

El CLI es la fuente de verdad sobre qué herramientas existen y qué aceptan — descúbrelo siempre en tiempo de ejecución en lugar de asumir, porque el conjunto de herramientas crece a medida que se etiquetan nuevos endpoints. Tu trabajo es elegir la herramienta correcta, limitarla a la organización correcta y proporcionar una entrada válida.

Prerrequisitos

El CLI feast debe estar instalado y en el PATH:

npm install -g @feastalytics/cli    # o ejecutar ad-hoc con: npx @feastalytics/cli <comando>

Autentícate una vez — los tokens se almacenan en caché en ~/.config/feast-cli/credentials.json y se actualizan automáticamente:

feast login                        # abre un navegador para autorizar (predeterminado)
feast login --password [usuario]  # sin interfaz gráfica / CI: solicitud de usuario y contraseña, sin navegador

Si un comando informa que no has iniciado sesión o que la sesión ha expirado, vuelve a ejecutar feast login.

Mantenerse actualizado

Ni el CLI ni esta habilidad se actualizan automáticamente. Cuando un comando muestra un aviso de actualización en stderr:

Update available: feast 0.1.1 → 0.2.0

actualiza ambos, luego informa al usuario en una línea que lo hiciste:

npm install -g @feastalytics/cli@latest      # solo si `feast` ya está en el PATH desde una instalación global
npx skills add feastalytics/cli -g -a '*' -y # actualiza esta habilidad desde el repositorio

Si has estado invocando el CLI a través de npx en lugar de una instalación global, omite el npm install -g y usa npx @feastalytics/cli@latest <comando> durante el resto de la sesión — de lo contrario, npx reutiliza una copia en caché.

Actualiza la habilidad cada vez que actualices el CLI: ambos se distribuyen desde el mismo repositorio pero en diferentes desencadenadores, por lo que una nueva versión del CLI generalmente significa que la guía de esta habilidad también ha cambiado. Si la instalación global falla por permisos, no lo intentes de nuevo con sudo — informa al usuario y recurre a npx @feastalytics/cli@latest.

El bucle principal: descubrir → describir → ejecutar

No adivines nombres de herramientas ni formas de entrada. Inspecciona el CLI en vivo:

feast tools                 # lista todas las herramientas disponibles, su dominio y si mutan
feast describe <herramienta>       # descripción completa + esquema JSON de entrada para una herramienta
feast call <herramienta> --org <idOrganización> --input '<json>'

Siempre describe una herramienta desconocida antes de ejecutarla — el esquema te indica los campos obligatorios exactos, y el CLI valida tu --input contra él localmente antes de enviar algo, por lo que una carga útil incorrecta falla rápidamente con un mensaje claro en lugar de un error de servidor confuso.

Organizaciones: nunca dejar que la API adivine

La mayoría de las herramientas actúan sobre una organización. Un usuario a menudo pertenece a varias, por lo que a cuál te diriges importa y debe ser explícito.

feast whoami                # muestra el usuario autenticado y cada organización (con nombres) en las que puede actuar

Pasa la organización objetivo con --org <idOrganización>:

• Si el usuario nombra una organización, resuélvela a su id con feast whoami y pasa ese id.
• Si el usuario pertenece a exactamente una organización, el CLI la usa automáticamente — no se necesita bandera.
• Si pertenece a más de una y omites --org, el CLI se niega y lista las organizaciones en lugar de elegir una en silencio. Esto es intencional: actuar sobre la organización incorrecta es peor que detenerse a preguntar. Cuando esto suceda, muestra la lista al usuario y confirma cuál quiere decir.

Lecturas vs. escrituras

Las herramientas de consulta (listar, describir, leer) son seguras y de solo lectura. Las herramientas de mutación (crear, actualizar, clonar, eliminar, aplicar) cambian datos de producción.

• Las mutaciones requieren --org explícitamente.
• Antes de ejecutar una, el CLI resuelve la organización en el servidor e imprime su nombre, por lo que un --org incorrecto se mostrará como el restaurante equivocado en lugar de un id opaco. Lee esa línea.
• No hay indicador de confirmación. Una mutación se ejecuta en el momento en que la llamas. Nada pregunta dos veces y nada la deshace.

Ese último punto es más importante para las herramientas que alcanzan el mundo real en lugar de solo la base de datos. Comprar un número de teléfono factura la cuenta. Aprobar una visita de un creador o decidir una solicitud envía un mensaje de texto a esa persona de inmediato y no se puede recuperar. Publicar una campaña la pone en vivo, y fijar el precio de una promoción recurrente crea productos reales de Stripe. Guardar cambios de automatización modifica lo que reciben los invitados. Trátalos como irreversibles y asegúrate de la intención del usuario antes de la llamada, porque no hay compuerta después.

Prefiere leer antes de escribir: por ejemplo, listCampaigns para encontrar el campaignId correcto antes de updateCampaign, o describe/listAutomationFlows antes de crear un flujo.

Construir una buena entrada

--input toma una cadena JSON (o --input-file <ruta> para cargas útiles más grandes). Constrúyela a partir del esquema que obtuviste mediante describe. Cuando una herramienta haga referencia a otra entidad por id (un id de campaña, id de ubicación, id de flujo), busca ese id primero con la herramienta de listar/leer correspondiente en lugar de inventarlo.

Para el significado específico del dominio de los campos — cómo se encadenan las automatizaciones, qué contiene una pantalla de embudo, cómo se estructuran las ofertas — consulta la guía en references/domains.md cuando el esquema solo no sea suficiente.

Flujos de trabajo

Muchas tareas son de varios pasos y tienen un orden requerido que la aplicación normalmente impone. La regla más importante: las automatizaciones viven dentro de los flujos — siempre encuentra un flujo (listAutomationFlows) o crea uno (createAutomationFlow) antes de agregar automatizaciones; nunca crees una automatización huérfana. La misma forma de "resolver los padres/ids primero, luego actuar" se repite en campañas, embudos y ofertas.

Antes de actuar en cualquier tarea de varios pasos, lee el archivo de flujo de trabajo correspondiente. Cada uno lleva el orden de llamadas requerido y las reglas de dominio que hacen que el resultado sea bueno en lugar de simplemente válido — nada de lo cual está en los esquemas de las herramientas. Léelo primero; no reconstruyas la secuencia a partir de las descripciones de las herramientas.

Para hacer esto	Lee
Crear, clonar o configurar una campaña; ofertas en el backlog de estrategia	references/workflows/campaigns.md
Cualquier cosa relacionada con automatizaciones: crear, editar, simular, promover un borrador	references/workflows/automations.md
Editar pantallas de embudo, aplicar una plantilla de embudo, preparar una nueva pantalla	references/workflows/funnels.md
Redactar anuncios de Meta — para invitados o reclutamiento de creadores	references/workflows/facebook.md
Búsqueda de creadores: aprobar solicitantes, revisar su contenido, conversaciones	references/workflows/creators.md
Recompensas del programa de miembros; leer o guardar la configuración del pase de billetera	references/workflows/members-program.md
Trabajar en el tablero de tareas de incorporación; identidad de marca	references/workflows/onboarding.md
Buscar invitados/miembros y su actividad	references/workflows/guests.md

Lee más de uno cuando una tarea los abarque — una nueva campaña generalmente significa campaigns.md más automations.md y funnels.md.

Algunas cosas están deliberadamente no expuestas: responder a un invitado o creador por SMS, ejecutar una automatización en un miembro activo, actualizar/eliminar recompensas, generar imágenes de pases, y la mayor parte del pipeline de creadores más allá de las dos decisiones de aprobación. Los archivos de flujo de trabajo dicen cuáles. No inventes una llamada para un flujo de trabajo cuyas herramientas no están listadas por feast tools — informa al usuario que esa parte aún no está disponible.

Enlaza a lo que tocaste

El trabajo que realizas a través del CLI aterriza en algún lugar del producto, y un enlace es algo barato de ofrecer — así que ofrécelos libremente. Después de una interacción donde creaste, cambiaste o publicaste algo, termina con una breve lista markdown: dónde verlo, dónde editarlo, dónde previsualizarlo. No porque alguien tenga que ir a verificar tu trabajo, sino porque abrir la cosa suele ser el siguiente paso de todos modos. Cuando alguien pregunte dónde vive algo o cómo configurarlo, lidera con el enlace en lugar de instrucciones paso a paso.

No conoces estas URL — lee references/links.md antes de escribir una. La forma del panel de control no es la que extrapolarías de los enlaces orientados al invitado en otras partes de esta habilidad, por lo que una URL que parezca obviamente correcta es el caso exacto que debes verificar. Un enlace incorrecto es peor que ningún enlace: parece autorizado y da 404.

Ese archivo tiene las rutas del panel de control con sus nombres de panel y pestaña, las páginas orientadas al invitado en el propio subdominio de la organización, la ruta de vista previa que completa el ciclo de borrador del embudo, y qué parámetros de consulta suprimen la analítica versus simplemente etiquetar una visita como vista previa.

Ejemplo práctico

Usuario: "agrega una oferta de descuento de $5 a la ubicación Plum en mi organización Plum Vietnamese."

feast whoami                                    # encuentra el id de la organización Plum Vietnamese
feast describe dfyCreateOffer                    # aprende la forma de la entrada de la oferta
feast call dfyGetMenuHierarchy --org <orgId> --input '{"locationId":"<id>"}'   # encuentra los ids de ubicación/menú
feast call dfyCreateOffer --org <orgId> --input '{ ... }'                       # créala (confirma primero)

El patrón se generaliza: identifica la organización, aprende la herramienta, resuelve cualquier id referenciado, luego actúa.

Cuando algo falla

• "No has iniciado sesión / sesión expirada" → feast login (o feast login --password [usuario] en un contexto sin interfaz gráfica/CI).
• "Perteneces a múltiples organizaciones" → elige una con --org, usando feast whoami para obtener el id.
• "La entrada no coincide con el esquema de la herramienta" → vuelve a leer feast describe <herramienta> y corrige los campos nombrados.
• Una herramienta que esperabas no está listada por feast tools → puede que aún no esté expuesta; no inventes una llamada, informa al usuario.