CLI

Resumen

La CLI refleja los flujos habituales del panel: iniciar sesión, crear endpoints de webhook, recibir tráfico capturado en tu máquina, compilar handlers en TypeScript y publicar versiones inmutables del pipeline.

• Cuenta: inicio de sesión en el navegador (login) con credenciales guardadas en disco para los siguientes comandos.
• Webhooks: crear endpoints (create) y suscribirte al relay en tiempo real (listen), con reenvío HTTP opcional a una URL local.
• Bundles: compilar cada entrada a .eventpipe/ (build) con tamaño y prefijo sha256.
• Despliegue: publicar una nueva versión del pipeline (push) con la misma sesión que la app.
• Herramientas: mostrar la versión instalada (--version), actualizar la CLI (update) y avisos opcionales de npm en stderr tras la mayoría de comandos.

Cuándo usarla

Úsala para builds repetibles desde Git, CI o iteración local rápida. Publicar desde Pipe Studio sigue siendo una opción completa; la CLI mantiene eventpipe.json y el código en el repo y encaja en automatización con Node en el runner.

Requisitos

• Se requiere Node.js 20 o superior.
• Cuenta en eventpipe (registro en la app).
• Para build y push: un eventpipe.json en la raíz del proyecto con pipelineId y settings.pipe (esquema v3).
• Para create, listen y push: ejecuta eventpipe login antes (salvo que ya exista sesión en esta máquina).

Instalación

• Global (recomendado): npm install -g @eventpipe/cli — añade los comandos eventpipe y eventpipe-cli al PATH.
• Como dependencia de desarrollo: npm add -D @eventpipe/cli, luego npx eventpipe … o scripts npm.

npm install -g @eventpipe/cli

npm add -D @eventpipe/cli
npx eventpipe --version

Autenticación

login abre el navegador para autenticarte con la misma cuenta que la web. Los tokens se guardan en disco y los reutilizan create, listen y push. No hay flujo solo con API key en la CLI: usa la sesión guardada por login.

• La URL base por defecto es https://eventpipe.app. En despliegues propios, define EVENTPIPE_BASE_URL con el origen de tu app (sin barra final) antes de login.
• Ruta de credenciales: ~/.eventpipe/credentials.json en Unix; en el perfil de usuario en Windows.
• Obligatorio antes de create, listen y push (salvo sesión válida existente).

export EVENTPIPE_BASE_URL=https://tu-app.example
# opcional; omite para eventpipe.app
eventpipe login

Inicio rápido

eventpipe create --name mi-endpoint
eventpipe listen <webhookId>

eventpipe login
eventpipe build   # opcional; push ejecuta build
eventpipe push

Estructura del proyecto y manifiesto

El pipelineId en eventpipe.json es el UUID del pipeline en Pipe Studio, no el id del endpoint de webhook. En Pipe Studio → Event → IDs for CLI & API, copia Pipeline id. El id del endpoint se usa en las URLs /webhook/… y con listen.

Con un solo nodo de código, el id del nodo en settings.pipe debe coincidir con el que empaquetas (entrada por defecto: src/handler.ts). Con varios nodos, define un mapa codeNodes: ruta de entrada → id de nodo.

• Campos opcionales: nodeId y entry (atajo de una sola entrada), o codeNodes (mapa multi-entrada).
• La salida generada queda en .eventpipe/ tras build o push.
• En producción, los secretos se leen en context.env en el handler, configurados en la pestaña Event de la app—no uses process.env dentro del bundle.

{
  "pipelineId": "TU_UUID_DE_PIPELINE",
  "settings": {
    "pipe": {
      "schemaVersion": 3,
      "nodes": [
        { "id": "code", "type": "code", "config": {} }
      ],
      "edges": []
    }
  }
}

{
  "pipelineId": "TU_UUID_DE_PIPELINE",
  "codeNodes": {
    "src/handler.ts": "ID_DE_NODO_1",
    "src/other.ts": "ID_DE_NODO_2"
  },
  "settings": {
    "pipe": {
      "schemaVersion": 3,
      "nodes": [
        { "id": "ID_DE_NODO_1", "type": "code", "config": {} },
        { "id": "ID_DE_NODO_2", "type": "code", "config": {} }
      ],
      "edges": []
    }
  }
}

type FlowEvent = {
  method: string;
  headers: Record<string, string>;
  body: unknown;
};

type FlowContext = { env?: Record<string, string> };

export async function handler(event: FlowEvent, _context: FlowContext) {
  return { ok: true, received: event.body };
}

build

Lee eventpipe.json desde el directorio actual o desde --dir. Empaqueta cada entrada con esbuild en .eventpipe/ e imprime tamaño en bytes, prefijo sha256 y rutas de salida. Cada bundle debe respetar el límite del plan (habitualmente 200KB UTF-8), validado en local y en el servidor.

• Flags: --dir <ruta> para otro directorio raíz del proyecto.
• Si hay varios nodos code y no defines codeNodes, la CLI resuelve una sola entrada cuando puede; si no, debes definir codeNodes (o nodeId + entry) explícitamente.

eventpipe build
eventpipe build --dir ./packages/api

push

Ejecuta el mismo empaquetado que build y luego hace POST de bundles y settings para crear una nueva versión inmutable del pipeline. La autenticación usa solo la sesión guardada por login.

• Flags: --dir <ruta>; --pipeline <uuid> o --flow <uuid> para sustituir pipelineId del eventpipe.json solo en esta ejecución.
• Si tiene éxito, la CLI imprime el id del pipeline, el número de la nueva versión y el tamaño total de bundles.

eventpipe push
eventpipe push --pipeline 00000000-0000-0000-0000-000000000000
eventpipe push --dir ./mi-pipeline

create

Crea un nuevo endpoint de webhook en tu cuenta. Requiere login.

• Opcional --name <slug> para pedir un slug de URL; si está ocupado, la CLI puede asignar otro id y avisar.
• La salida incluye la URL del webhook y el id—usa el id con listen.

eventpipe create
eventpipe create --name mi-endpoint

listen

Transmite los webhooks capturados para ese id de endpoint a través del relay. Requiere login. El despliegue debe exponer un relay compatible (comportamiento por defecto del producto).

eventpipe listen abc123
eventpipe listen abc123 -v
eventpipe listen abc123 --json | jq .
eventpipe listen abc123 --forward-to http://127.0.0.1:3000/webhook

MCP para agentes de IA

La CLI incluye un servidor MCP (Model Context Protocol) integrado para que agentes de IA en Cursor, Claude Code, Claude Desktop u otro cliente compatible con MCP puedan inspeccionar y depurar tus pipelines directamente. Un solo comando crea la API key, guarda credenciales en ~/.eventpipe/mcp.json y fusiona la misma entrada del servidor en cada configuración de editor que elijas.

eventpipe login
eventpipe mcp setup
eventpipe mcp setup --client cursor

update

Ejecuta npm install -g @eventpipe/cli@latest (en Windows usa npm.cmd). Úsalo cuando la CLI sugiera una versión más reciente en stderr.

Versión, ayuda y avisos de actualización

• eventpipe --version o eventpipe -v muestra la versión instalada del paquete.
• eventpipe, eventpipe help o eventpipe --help muestra el uso (banner, comandos, entorno).
• Tras la mayoría de comandos, la CLI puede consultar npm por una versión más nueva de @eventpipe/cli e imprimir una pista en stderr. Define EVENTPIPE_SKIP_UPDATE_CHECK=1 para desactivarlo (recomendado en CI ruidoso).

Variables de entorno

Límites y automatización

Cada bundle de nodo code debe respetar el tope de tu plan (habitualmente 200KB). Los pipelines con varios nodos code requieren mapear cada nodo con codeNodes (o un diseño inequívoco de un solo nodo); los grafos grandes también se pueden publicar desde Pipe Studio.

En CI, ejecuta login en un runner seguro o restaura credenciales en ~/.eventpipe antes del push; trata ese directorio como material secreto.

• Los límites por plan se resumen en Precios.
• El contrato de publicación coincide con POST /api/account/pipelines/{id}/versions en la referencia API.