# CLI (met) `met` es la terminal de Meteor: ejecuta un Met, sigue el historial de runs, abre un chat y —lo más útil mientras integras— **escucha los eventos de tu workspace y los reenvía a tu servidor local**. ```bash npm i -g @meteor.ia/cli ``` Node ≥ 20. Usa la misma API key `met_` que el SDK. ## Configurar ```bash met config set --key met_live_xxx --workspace 7 met config show # la key sale enmascarada ``` Queda en `~/.config/met/config.json`. También lee `MET_API_KEY`, `MET_WORKSPACE` y `MET_BASE_URL` del entorno, y cualquier comando acepta `--key` / `--workspace` para un uso puntual. En CI, usa las variables de entorno. Mientras desarrollas, usa una key **de test** (`met_test_`): los runs no cuestan y los efectos externos quedan bloqueados. ## Ejecutar un Met ```bash met run "Resume los leads de hoy" ``` En una terminal interactiva streamea por defecto. Para un pipeline o un cron: ```bash met run "Hola" --json --no-stream ``` `--json` imprime el objeto completo en una línea, listo para `jq`. `--met ` elige qué Met ejecuta si no quieres el del workspace. ```bash met runs list --status failed --limit 20 ``` ## Ejecutar una tarea Una tarea es un procedimiento con pasos que tu Met ejecuta. Desde la terminal: ```bash met tasks list met tasks run tsk_123 ``` `run` dispara la ejecución y devuelve enseguida, porque los pasos corren en segundo plano. Para un cron o un pipeline eso no alcanza —el comando diría "ok" por haber podido disparar, no por haber funcionado— así que usa `--wait`: ```bash met tasks run tsk_123 --wait ``` Con `--wait` el comando espera el estado final y **el código de salida refleja el resultado**: `0` si terminó completada, `1` si falló o se canceló. El tope por defecto son 300 segundos; súbelo con `--timeout 900`. ```bash met tasks show tsk_123 # la tarea y sus últimas ejecuciones met tasks executions tsk_123 --json ``` ## Chat ```bash met chat --met ventas ``` Un REPL sobre el mismo stream de runs. Sirve para probar un prompt sin escribir código. ## Escuchar eventos, y reenviarlos a tu máquina Este es el comando por el que vale la pena instalar el CLI: ```bash met listen --forward http://localhost:3000/webhooks ``` Toma los eventos del workspace en vivo y los **POSTea a tu servidor local**, así desarrollas el handler de webhooks sin exponer tu máquina a internet ni configurar un túnel. Filtra lo que te interesa: ```bash met listen --types run.completed,run.failed ``` Sin `--forward` los imprime, que alcanza para ver qué está pasando. El catálogo de eventos está en [Webhooks](webhooks.html#catalogo-de-eventos). ## Colecciones e ítems Las colecciones son las bases de datos no-code del workspace, y son el paso previo de todo lo demás: sin el id de una colección no puedes listar ni crear nada adentro. ```bash met collections list met collections show 12 # el esquema de campos ``` `show` imprime los campos con su tipo porque esas claves son exactamente las que después usas para escribir: ```bash met items list --collection 12 --limit 20 met items create --collection 12 --set titulo="Casa en el norte" --set precio=250000 met items update 9812 --collection 12 --set estado=vendido ``` `--set` es repetible y se escribe sin escapar nada, que es lo que quieres en una terminal. Se parte en el **primer** `=`, así que una URL con query pasa entera. Ojo con los tipos: del shell todo llega como texto, y `--set` convierte solo lo que no tiene ambigüedad. `true`, `false`, `null` y los números pasan; `007`, `1.50` y `1e3` quedan como texto porque no sobreviven el viaje de ida y vuelta. Lo que **no** puede distinguir es un teléfono `3001234567` de una cantidad — para esos casos, pasa el JSON y el tipo lo pones tú: ```bash met items create --collection 12 --data '{"telefono":"3001234567"}' ``` `--data` gana sobre `--set` si pasas las dos. ## Contactos ```bash met contacts list --limit 50 met contacts show 42 # el contacto y sus últimos mensajes met contacts send 42 "Ya quedó agendada la visita" ``` `send` manda como **operador humano**, no como Met: es el equivalente de escribir desde la bandeja, y el mensaje queda atribuido a una persona en el historial. Si lo que quieres es que responda un Met, eso es `met run`. ## Qué Mets hay `met run --met ` necesita el nombre de un Met. Para verlos: ```bash met agents list met agents show 3 # sus herramientas ``` `show` imprime las herramientas porque responde la pregunta siguiente — *"¿por qué el Met no hace X?"*, que casi siempre es que no tiene la herramienta, no que el prompt esté mal. ## Cuánto estás gastando ```bash met billing resumen --from 2026-07-01 --to 2026-07-31 met billing ejecuciones # el detalle, ordenado por costo met billing saldo ``` `resumen` es el agregado del período y `ejecuciones` el detalle. **Cuando la factura no cuadra, la respuesta está en el detalle**: recorre todas las ejecuciones y las ordena por costo, y arriba casi siempre aparece un Met que se llama a sí mismo en un bucle. `saldo` avisa si la recarga automática está apagada. Importa más de lo que parece en una integración desatendida: quedarse sin Energía **detiene las ejecuciones**, y del lado del cliente eso se ve como "la API dejó de responder". ## Depurar webhooks Es el par de `met listen`: ese trae los eventos a tu máquina, y esto responde la otra mitad — *"el webhook está configurado, ¿por qué mi servidor no recibe nada?"*. ```bash met webhooks list met webhooks events 12 # historial de entregas, con el código HTTP met webhooks sample 12 # dispara un evento de prueba ``` Si `events` sale vacío, la respuesta ya está: el webhook **nunca se disparó**, así que el problema está en el disparador y no en tu endpoint. Es solo lectura y prueba a propósito: crear un webhook o rotar su secreto se hace desde el panel. Un secreto que queda en el historial de shell es exactamente lo que no se quiere. ## Provisionar un workspace desde un script Una plantilla (Snapshot) monta un vertical completo en el workspace: colecciones, Mets, flujos y contenido. Desde la terminal puedes hacerlo sin abrir el panel, que es lo que necesitas cuando das de alta un cliente nuevo desde tu propio onboarding o desde CI. ```bash met snapshots list --vertical inmobiliaria met snapshots show inmobiliaria-basica # qué incluye y qué variables pide ``` `show` imprime las variables con un `*` en las obligatorias. Son los datos del negocio que la plantilla usa para personalizar prompts y contenido, y se pasan al instalar: ```bash met snapshots claim 3f1e… # solo para plantillas gratuitas met snapshots install 3f1e… --set negocio="Muebles del Norte" --set ciudad=Medellín ``` `install` necesita que el workspace ya tenga acceso a la plantilla: `claim` lo da para las gratuitas, y las de pago se compran desde el panel. Aquí `--set` **no convierte tipos**: un teléfono o un NIT quedan como texto, que es lo que son. Si una variable de verdad no es texto, pásala en JSON con `--vars '{"cupo":10}'`. La instalación es aditiva e idempotente, y **todo llega desactivado**: `install` imprime el id en stdout y el estado en stderr, así que en un pipeline puedes guardar el id y revisar antes de prender nada. ## Cuando algo no funciona ```bash met whoami ``` Distingue los tres casos que desde afuera se ven idénticos: la key está mal (**401**), la key es válida y le falta el scope de la operación (**403**), o todo está bien. El segundo es el que más tiempo hace perder, porque autentica sin problema y aun así la operación falla — y la primera sospecha siempre cae en la key. También te dice contra qué host y qué workspace estás pegando, que es el otro error silencioso. ## Si eres partner Tu negocio de partner también se consulta desde la terminal, con la misma key: ```bash met partner leads --status won met partner clients met partner commissions --status approved --json met partner payouts --period 2026-07 ``` Los recursos son `clients`, `leads`, `projects`, `commissions` y `payouts`. Son de **solo lectura**: crear una oportunidad o mover una etapa se hace por [SDK](../partners.html) o desde el panel — no es algo que convenga disparar de un tirón en una terminal. La excepción es soporte, que sí escribe: ```bash met partner tickets list met partner tickets show 84 # el hilo completo met partner tickets reply 84 "Ya quedó corregido, prueba de nuevo" ``` `show` imprime los mensajes y no solo la cabecera, porque lo siguiente que vas a escribir es `reply`. Abrir un ticket y cerrarlo se hacen desde el panel o por SDK. Una key de partner no tiene workspace, y estos comandos no lo necesitan. El host de la API de Partners es otro, así que si apuntas a un entorno distinto se configura aparte: ```bash met config set --partner-base-url https://api.partners.meteor.com.co ``` ## Todos los comandos | comando | qué hace | |---|---| | `met run ` | ejecuta un Met y muestra la salida | | `met runs list` | historial de runs (`--status`, `--limit`, `--json`) | | `met tasks list` | tareas del workspace | | `met tasks run ` | dispara una tarea (`--wait`, `--timeout`) | | `met tasks show ` | la tarea y sus últimas ejecuciones | | `met tasks executions ` | historial de ejecuciones | | `met agents list\|show` | los Mets del workspace y sus herramientas | | `met billing resumen\|ejecuciones\|saldo` | consumo de Energía; `ejecuciones` es el detalle por costo | | `met webhooks list\|show\|events\|sample` | depurar entregas de webhook | | `met collections list\|show` | colecciones del workspace y su esquema de campos | | `met items list\|show\|create\|update` | filas de una colección (`--collection`, `--set`, `--data`) | | `met contacts list\|show\|send` | CRM y envío como operador | | `met partner ` | tu negocio de partner (solo lectura) | | `met partner tickets list\|show\|reply` | soporte: el hilo de un ticket y tu respuesta | | `met snapshots list\|show\|claim\|install` | plantillas: catálogo, ficha e instalación (`--set`, `--vars`) | | `met chat` | REPL interactivo | | `met listen` | eventos en vivo (`--types`, `--forward`) | | `met config set\|show` | guarda o muestra la configuración | | `met whoami` | verifica la key activa: autenticación, scope y host | | `met help` | la ayuda completa | ## Opciones comunes | opción | para qué | |---|---| | `--met ` | qué Met ejecutar (por defecto, el del workspace) | | `--workspace ` | workspace destino (o `MET_WORKSPACE`) | | `--key ` | API key (o `MET_API_KEY`, o la guardada) | | `--base-url ` | host de la API (o `MET_BASE_URL`), para apuntar a otro entorno | | `--partner-base-url ` | host de la API de Partners (o `MET_PARTNER_BASE_URL`) | | `--json` | salida en JSON, para pipes y CI | | `--no-stream` | espera el resultado completo en vez de streamear | ## Lo que todavía no hace El CLI cubre **runs**, **Mets**, **tareas**, **colecciones**, **ítems**, **contactos**, **flujos**, **webhooks**, **facturación**, **eventos**, **plantillas** y el negocio de partner (lectura, más los tickets de soporte). Los que quedan afuera —habilidades, canales, automatizaciones, integraciones, funciones— se operan por [SDK](../index.html#quickstart) o REST, donde están completos. No es un hueco a llenar por simetría: un CLI sirve para lo que uno hace de a un comando, en un cron o probando algo. Configurar un webhook o activar una habilidad se hace una vez y desde el panel. Las **API keys se crean desde el panel** (Ajustes → Desarrolladores), no desde la terminal: emitir credenciales desde un CLI es la clase de cosa que termina en un historial de shell. Para verificar la que estás usando, `met whoami`.