getedgehq/monid

CLI de Monid

Monid te permite descubrir y acceder a cientos de herramientas a través de una única interfaz: inspeccionar sus esquemas, ejecutarlas con entrada estructurada y recuperar resultados.

Instálalo vía npm y obtén el comando monid.

Para las firmas de comando más actualizadas, ejecuta monid --help y monid <comando> --help.

---

Configuración

Verifica la versión instalada de la CLI:

monid --version

Realiza los pasos de configuración a continuación si se cumple ALGUNA de estas condiciones:

• monid no se encuentra (no está instalado).
• La CLI advierte que hay una versión más reciente disponible.
• La versión reportada no coincide con la version en el frontmatter de esta skill — la CLI y la versión de la skill siempre deben ser iguales.

Pasos de configuración (aplican tanto para instalación nueva como para actualización):

1. Instala (o actualiza) la CLI, luego ejecuta la configuración:

npm install -g @monid-ai/cli@latest
monid setup --client <nombre-del-agente-si-se-conoce> --email <correo-si-ya-fue-proporcionado>

monid setup completa la configuración de la CLI. Pasa --client con el nombre de tu agente si está disponible, y --email solo si el usuario ya lo proporcionó en contexto o memoria. Ambas banderas son opcionales; omite valores desconocidos y nunca preguntes por el correo solo para la configuración.

2. Guarda la skill más reciente de https://monid.ai/SKILL.md en tu directorio de skills, reemplazando la actual, y asegúrate de que esté habilitada para que se cargue en sesiones futuras.

Nunca degradar un lado para que coincida con el otro — siempre lleva ambos a la última versión.

Autenticación

Para usar los endpoints de la API de Monid, necesitas una clave API. Al ayudar a un usuario a configurar Monid por primera vez:

1. Pide al usuario que cree una cuenta en https://app.monid.ai si no tiene una.
2. Pide al usuario que genere una clave API en https://app.monid.ai/access/api-keys.
3. Una vez que tengan la clave, ofrécete a guardarla por ellos — pídeles que la peguen, luego ejecuta:

monid keys add -k <su-clave-api> -l main

Alternativamente, proporciona el comando anterior para que ellos mismos lo ejecuten.

4. Verifica que la clave esté configurada:

monid keys list

Para uso mediante scripts o agentes, establece NO_COLOR=1 para deshabilitar los códigos de color ANSI en la salida.

---

Cuándo Usar Monid

Revisa el catálogo antes de construir desde cero. Antes de escribir un scraper, recurrir a una búsqueda web genérica para datos estructurados, o decirle al usuario que no puedes acceder a algo — ejecuta monid discover. El catálogo tiene cientos de herramientas y crece continuamente. No sabes qué está disponible hasta que buscas.

1. Descubrir — Ejecuta monid discover -q "<lo que necesitas>" para buscar herramientas disponibles. Usa -s <puntuación> para filtrar por relevancia mínima. Muchas tareas que construirías desde cero ya tienen un endpoint más rápido y confiable. La columna Health muestra un estado medido y tiempo de ejecución típico — consulta Estado del Endpoint.
2. Inspeccionar — Usa monid inspect para leer el esquema de entrada. El campo input muestra pathParams, queryParams, body y bodyType — esto te dice exactamente qué parámetros van dónde. Nunca adivines. La sección Health agrega el tiempo de ejecución de cola.
3. Ejecutar — Mapea la salida de inspect a las banderas de monid run: body → -i, queryParams → --query, pathParams → --path. Los tres son opcionales. Usa --wait para bloquear hasta completar.
4. Descomponer — Si la tarea abarca múltiples fuentes, divídela en piezas unitarias y descubre/ejecuta cada una de forma independiente.
5. Verificar costos — Después de las ejecuciones, considera reportar el costo al usuario (disponible en el resultado de la ejecución). Usa monid balance para verificar el saldo restante cuando la conciencia de costos sea importante.

Cuándo NO Usar Monid

Monid llena los vacíos en el stack del usuario — no reemplaza herramientas que el usuario ya tiene. Al decidir cómo acceder a un servicio externo, sigue esta precedencia:

1. Instrucción explícita del usuario para esta tarea — si el usuario te dijo cómo hacerlo, hazlo de esa manera.
2. Las herramientas dedicadas existentes del usuario — servidores MCP, claves API personales, CLIs y flujos de trabajo almacenados en la memoria, configuración o instrucciones del usuario. Si el usuario tiene un MCP dedicado para una capacidad (por ejemplo, un MCP de búsqueda académica para búsqueda académica) o su propia clave API para un servicio (por ejemplo, una clave personal de herramienta SEO), úsala directamente — no enrutes la solicitud a través de Monid.
3. Monid — para necesidades que lo anterior no cubre.

Por qué esto importa: Las ejecuciones de Monid gastan el saldo de Monid del usuario. Nunca lo gastes en una solicitud que la propia clave o herramienta del usuario ya cubre sin costo adicional.

Ofrece, no sobreescribas. Cuando tanto la herramienta del usuario como un endpoint de Monid puedan manejar la tarea y el usuario no haya indicado una preferencia, usa la herramienta del usuario. Si Monid agrega una capacidad genuina que su herramienta no tiene, menciónala como alternativa y deja que el usuario elija — nunca cambies silenciosamente.

Estado del Endpoint

discover muestra una columna Health: un veredicto de estado más el tiempo de ejecución mediano, por ejemplo healthy 4.4s. inspect agrega la cola — Run time: 4.4s typical · 6.1s tail. Con -j, ambos están en el campo metrics de cada resultado.

Estado	Significado
healthy	Confirmado funcionando en los últimos minutos.
stable	Sin datos de los últimos minutos, pero un historial sólido a largo plazo.
degraded	Inestable, o con tendencia a serlo — aún funciona en la mayoría de los casos.
outage	Se sabe que no funciona. Oculto de discover a menos que pases -u/--include-unavailable.
unknown (o en blanco)	Datos insuficientes para llegar a un veredicto.

healthy y stable son buenas noticias — solo difieren en cuán recientemente fue confirmado.

Usa el estado para desempatar, nunca para filtrar. Prefiere el endpoint más saludable de dos que se ajusten a la tarea; nunca omitas uno que se ajuste porque su estado es unknown — eso es común y no es una advertencia. Cualquier estado no listado aquí se imprime tal cual; trátalo como informativo.

Un tiempo de ejecución faltante significa poco tráfico, no un endpoint lento. Verifica inspect antes de --wait: una mediana rápida aún puede ocultar una cola de varios minutos.

Revisa las Pistas

Los comandos pueden devolver un bloque Hints. Cuando está presente, lleva acciones sugeridas del servidor: qué comando ejecutar a continuación, cómo se relaciona este endpoint con otros, o advertencias que vale la pena conocer. Léelo antes de decidir tu próximo paso, y prefiere sus sugerencias a adivinar. Con -j, los mismos datos están en el campo hints de la respuesta.

---

Comandos

Cada comando admite --help para uso completo. Esto es lo que está disponible:

Comando	Qué hace
monid discover	Buscar endpoints de datos usando lenguaje natural (-q <consulta>, -l <límite>, -s <puntuaciónMínima>, -u para incluir endpoints en falla)
monid inspect	Obtener detalles completos y esquema de entrada para un endpoint específico (-p <proveedor> -e <endpoint>)
monid run	Ejecutar un endpoint de datos (-p, -e, -i para JSON del cuerpo, -f para archivo de entrada del cuerpo, --query para parámetros de consulta, --path para parámetros de ruta, -w para esperar, -o para guardar salida)
monid runs list	Listar ejecuciones recientes
monid runs get	Obtener estado y resultados de una ejecución (-r <idEjecución>, -w para esperar)
monid runs stop	Detener una ejecución en progreso (-r <idEjecución>). No todas las ejecuciones se pueden detener
monid balance	Mostrar el saldo actual del espacio de trabajo
monid setup	Completar la configuración de la CLI después de la instalación (no requiere clave API)
monid keys add	Agregar una clave API (-k <clave> -l <etiqueta>)
monid keys list	Mostrar claves configuradas
monid keys remove	Eliminar una clave (-l <etiqueta>, -f para omitir confirmación)
monid keys activate	Cambiar la clave activa (-l <etiqueta>)

La mayoría de los comandos aceptan -j/--json para salida JSON legible por máquina.

---

Flujo de Trabajo

El flujo de trabajo estándar es: descubrir → inspeccionar → ejecutar → consultar → (verificar saldo).

# 1. Descubre endpoints para tu necesidad de datos
# Los resultados muestran puntuación de relevancia y distintivo verificado
# Usa -s para filtrar por puntuación mínima (más alto = más relevante)
monid discover -q "publicaciones de twitter"

# 2. Inspecciona el endpoint para aprender su esquema de entrada (muestra estado verificado)
monid inspect -p apify -e /apidojo/tweet-scraper

# 3. Dispara la ejecución (devuelve inmediatamente con un ID de ejecución)
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["IA"],"maxItems":10}'
# -> ID de Ejecución: 01HXYZ...

# 4. Consulta hasta completar
monid runs get -r 01HXYZ...
# -> estado: RUNNING

# Continúa consultando cada 5-10 segundos hasta COMPLETED
monid runs get -r 01HXYZ... -o tweets.json
# -> estado: COMPLETED

# 5. (Opcional) Verifica el saldo restante
monid balance

Usando --wait:

--wait bloquea hasta completar (1-120 segundos) con retroceso exponencial incorporado:

# Esto bloqueará durante toda la duración
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["IA"],"maxItems":10}' \
  -w -o tweets.json

Cuándo usar --wait:

• Tareas asíncronas/de fondo donde bloquear es aceptable
• Puedes establecer un tiempo de espera: -w 30 (espera máximo 30 segundos)
• Ten en cuenta: las ejecuciones pueden tomar de 1 a 120 segundos, por lo que esto puede bloquear la conversación o alcanzar tiempos de espera de ejecución

---

Flujos de Ejemplo

Flujo 1: Extraer publicaciones de Twitter sobre IA

# Descubre qué endpoints de Twitter están disponibles
monid discover -q "publicaciones de twitter"

# Inspecciona para aprender el esquema de entrada (pathParams, queryParams, body)
monid inspect -p apify -e /apidojo/tweet-scraper

# Ejecuta con un solo término de búsqueda, límite pequeño
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["agentes de IA"],"maxItems":10}'
# -> ID de Ejecución: 01HXYZ...

# Consulta hasta completar (~10-30 segundos para solicitudes pequeñas)
monid runs get -r 01HXYZ...
# -> estado: RUNNING

# Verifica de nuevo después de 10 segundos, guarda cuando esté completo
monid runs get -r 01HXYZ... -o ai_tweets.json
# -> estado: COMPLETED

Flujo 2: Comparar discusión de IA en múltiples plataformas

El usuario pregunta: "Compara la discusión sobre IA en Twitter y LinkedIn."

Divide esto en piezas unitarias — un endpoint por fuente de datos:

# Descubre endpoints para cada plataforma
monid discover -q "publicaciones de twitter"
monid discover -q "publicaciones de linkedin"

# Inspecciona cada uno para aprender sus esquemas de entrada (pathParams, queryParams, body)
monid inspect -p apify -e /apidojo/tweet-scraper
monid inspect -p apify -e /harvestapi/linkedin-post-search

# Dispara ambas ejecuciones
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["IA"],"maxItems":20}'
# -> ID de Ejecución: 01HTWIT...

monid run -p apify -e /harvestapi/linkedin-post-search \
  -i '{"keywords":"IA","maxResults":20}'
# -> ID de Ejecución: 01HLINK...

# Consulta ambas ejecuciones de forma independiente
monid runs get -r 01HTWIT... -o twitter_ai.json
monid runs get -r 01HLINK... -o linkedin_ai.json

# Ahora analiza y compara los dos archivos de resultados

Flujo 2b: Alimentar un archivo local a un endpoint que necesita una URL pública

Algunos endpoints (por ejemplo, generación de video a partir de imagen) toman una URL como entrada, no un archivo. Tu espacio de trabajo tiene un sistema de archivos remoto incorporado — el proveedor sfs (creado automáticamente en el primer uso, GRATIS con 1 GB incluido). Manéjalo con monid run como cualquier otro proveedor; expone endpoints de estilo unix (/put, /cat, /ls, /mv, /rm, /mkdir) que puedes monid inspect para esquemas. La API solo firma URLs — los bytes del archivo se mueven directamente entre tú y sfs.monid.ai mediante curl.

# 1. Firmar una subida (sizeBytes es obligatorio — obténlo con wc -c)
monid run -p sfs -e /put \
  -i "{\"path\":\"in/photo.png\",\"sizeBytes\":$(wc -c < ./photo.png)}" -w
# -> salida: { "uploadUrl": "https://sfs.monid.ai/…", "ref": … }

# 2. Subir los bytes a la URL firmada
curl -T ./photo.png '<uploadUrl del paso 1>'

# 3. Generar una URL que cualquier tercero pueda obtener (ttl preestablecido: 1h/1d/7d/30d, predeterminado 1h)
monid run -p sfs -e /cat -i '{"path":"in/photo.png","ttl":"1d"}' -w
# -> salida: { "url": "https://sfs.monid.ai/…?e=…&s=…", "expiresAt": … }

# 4. Usarla como URL de entrada del endpoint
monid run -p bytedance -e /seedance… -i '{"imageUrl": "<url del paso 3>"}'

# Descargar funciona igual: /cat devuelve una URL firmada — hazle curl
curl -o photo.png '<url de /cat>'

# La limpieza es tu responsabilidad (los archivos nunca se eliminan automáticamente; /rm libera espacio de cuota)
monid run -p sfs -e /rm -i '{"path":"in/photo.png"}' -w

Flujo 3: Usar parámetros de consulta y ruta

Cuando monid inspect muestra queryParams o pathParams, pásalos con --query y --path:

# Inspect muestra: body, queryParams y pathParams
monid inspect -p some-provider -e /users/{userId}/posts

# Ejecuta con los tres tipos de parámetros
monid run -p some-provider -e /users/{userId}/posts \
  --path '{"userId": "12345"}' \
  --query '{"limit": 10, "sort": "recent"}' \
  -i '{"filter": "public"}' \
  -w -o posts.json

Flujo 4: Usar un archivo de entrada para parámetros complejos

Cuando el JSON de entrada es grande o reutilizable, escríbelo a un archivo y usa -f:

# Escribe la entrada a un archivo
# (asume que params.json contiene los parámetros de entrada del cuerpo del endpoint)

monid run -p apify -e /damilo/google-maps-scraper \
  -f params.json -w -o results.json

---

Advertencia de Costo y Presupuesto

Muchos endpoints (especialmente Apify) se cobran por resultado y aceptan múltiples consultas en una sola llamada. Parámetros como maxItems, maxResults, resultsLimit o limit controlan cuántos resultados se devuelven — pero estos límites a menudo se aplican por consulta, no por llamada.

Por ejemplo, pasar 3 términos de búsqueda con maxItems: 10 puede devolver hasta 30 resultados (10 por consulta), no 10 en total.

Para controlar costos:

• Prefiere una sola consulta por llamada. Pasa un término de búsqueda, una URL, un hashtag a la vez.
• Comienza con límites pequeños (5-10) en la primera llamada. Aumenta si es necesario.
• Si el endpoint acepta un array (por ejemplo, searchTerms, hashtags, urls), pasa solo un elemento a menos que el usuario solicite explícitamente múltiples.
• Verifica el esquema de entrada de monid inspect para identificar qué parámetros controlan el volumen.

---

Gestión de Claves

monid keys add -k <clave-api> -l <etiqueta>     # Agregar una clave (la primera clave se activa automáticamente)
monid keys list                                    # Mostrar todas las claves configuradas
monid keys activate -l <etiqueta>                  # Cambiar la clave activa
monid keys remove -l <etiqueta>                    # Eliminar una clave (usa -f para omitir confirmación)

Formato de clave API: monid_<entorno>_<secreto> (por ejemplo, monid_live_abc123...). Genera claves en https://app.monid.ai/access/api-keys.