Cómo usar la CLI de Apidog en el Agente Hermes

Hermes Agent se ejecuta desde tu terminal, conserva contexto entre sesiones y usa comandos de shell reales para completar tareas. Si puede ejecutar un comando, también puede ejecutar tus pruebas de API.

Prueba Apidog hoy

El puente con tus pruebas es la CLI de Apidog, el paquete npm apidog-cli. Con ella puedes ejecutar desde la terminal los escenarios que construiste visualmente en Apidog y obtener un código de salida que Hermes puede interpretar. En esta guía verás cómo configurar Hermes para usar apidog run, cómo guardar ese flujo en AGENTS.md, cómo validar el resultado y cómo conectar opcionalmente el servidor MCP de Apidog para que Hermes lea tu especificación de API mientras trabaja.

Si aún no tienes la CLI instalada, empieza con cómo instalar la CLI de Apidog con un agente de codificación de IA. Continúa cuando este comando devuelva una versión:

apidog --version

También necesitas una cuenta de Apidog con al menos un escenario de prueba guardado.

Qué significa usar la CLI de Apidog en Hermes

Hermes Agent, desarrollado por Nous Research, se ejecuta en tu terminal y actúa mediante herramientas integradas. La importante aquí es terminal: Hermes llama comandos de shell en tu directorio de trabajo, lee la salida y decide el siguiente paso.

No necesitas un plugin de Apidog para Hermes. El flujo consiste en:

1. Guardar instrucciones en AGENTS.md para que Hermes conozca el comando, los flags y la regla del código de salida.
2. Ejecutar apidog run desde la herramienta terminal como cualquier otro comando de shell.
3. Opcionalmente conectar el servidor MCP de Apidog para que Hermes consulte tu especificación de API mientras modifica código.

El archivo de contexto convierte una instrucción puntual como “ejecuta mis pruebas” en una regla reutilizable para cada sesión del repositorio.

El mecanismo: usa un archivo de contexto, no un recordatorio en el chat

Hermes carga contexto del proyecto al iniciar una sesión. Su motor escanea el directorio de trabajo en busca de archivos como:

• AGENTS.md
• CLAUDE.md

Luego inyecta esas instrucciones en el system prompt. Si tu repositorio ya usa AGENTS.md, Hermes también lo lee.

Por eso debes guardar el flujo de Apidog en un archivo del repositorio. Un ID de escenario escrito en el chat se pierde al cerrar la sesión; uno en AGENTS.md queda disponible para el equipo y para futuras ejecuciones de Hermes.

Hermes también puede leer SOUL.md, pero ese archivo es para la personalidad del agente. Mantén las instrucciones de pruebas en AGENTS.md.

Paso 1: añade un bloque de Apidog a AGENTS.md

Crea o abre AGENTS.md en la raíz del repositorio y añade una sección explícita. Incluye el comando real, las IDs reales y la regla de éxito/fallo.

## Pruebas de API con la CLI de Apidog

Este repositorio utiliza la CLI de Apidog (`apidog-cli`, comando `apidog`) para ejecutar escenarios de prueba de API. Los escenarios viven en nuestro proyecto de Apidog, no en este repositorio.

Cuando cambies un manejador de API, una ruta o la forma de una respuesta, ejecuta el escenario de Apidog relevante mediante la herramienta de terminal antes de considerar el cambio como finalizado:

    apidog run -t 605067 -e 1629989 -n 1 -r cli

- `-t 605067` es el escenario de prueba del flujo de pago.
- `-e 1629989` es el entorno de staging.
- La máquina ya está autenticada con `apidog login`, así que NO pases un token de acceso y NO imprimas uno.

Trata el código de salida como la fuente de la verdad:
- `0` significa que todas las aserciones pasaron.
- Cualquier valor distinto de cero significa fallo.

Si el comando sale con un valor distinto de cero, lee la aserción fallida en el informe, corrige el código y vuelve a ejecutar. No informes éxito si el código de salida no es `0`.

Cambia:

• 605067 por tu ID real de escenario.
• 1629989 por el ID del entorno que Hermes debe usar normalmente.

Usa staging o desarrollo local. Evita producción para ejecuciones automatizadas desde un agente.

Este bloque funciona por dos razones:

• Le da a Hermes el comando exacto, sin dejarle adivinar flags.
• Define que el código de salida prevalece sobre cualquier resumen textual.

Eso evita el fallo típico: que el agente diga “las pruebas pasaron” aunque el proceso haya terminado con error.

Paso 2: obtén el comando desde Apidog

Antes de pedirle a Hermes que ejecute pruebas, valida el comando manualmente.

En Apidog:

1. Abre tu escenario de prueba.
2. Ve a la pestaña CI/CD.
3. Elige la opción de línea de comandos.
4. Copia el comando apidog run.

Apidog genera un comando similar a este:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli

Donde:

• 605067 es la ID del escenario.
• 1629989 es la ID del entorno.

Como la CLI ya está autenticada en tu máquina, elimina --access-token YOUR_ACCESS_TOKEN antes de pegar el comando en AGENTS.md.

El comando que debe quedar es:

apidog run -t 605067 -e 1629989 -n 1 -r cli

No guardes tokens en archivos versionados.

Paso 3: haz que Hermes ejecute la prueba

Inicia Hermes desde la raíz del repositorio. Luego pídele que ejecute el escenario usando las instrucciones del archivo de contexto:

Ejecuta nuestro escenario de prueba de API de Apidog como describe AGENTS.md. Ya estoy autenticado, así que no pases un token de acceso. Usa apidog run -t 605067 -e 1629989 -n 1 -r cli. Muéstrame la salida completa y dime el código de salida.

Hermes ejecutará el comando mediante su herramienta terminal.

El reporter -r cli muestra el resultado paso a paso en la terminal, incluyendo solicitudes, respuestas y aserciones. Según tu configuración, Hermes puede pedir aprobación antes de ejecutar el comando. Un escenario de solo lectura contra staging suele ser un comando seguro para permitir.

Tu verificación debe ser simple:

Código de salida 0      => pruebas correctas
Código de salida != 0   => fallo

apidog run sale con 0 cuando todas las aserciones pasan. Si alguna falla, sale con un valor distinto de cero.

Si Hermes resume “pruebas pasadas” pero el código de salida no fue 0, el resumen está mal. Confía en el código de salida.

Para consultar flags disponibles, pídele a Hermes que ejecute:

apidog run --help

La guía completa de la CLI de Apidog documenta los reporters cli, html, json y junit, entre otros flags.

Paso 4: integra Apidog en el ciclo de Hermes

La parte útil no es ejecutar una prueba una vez. Lo útil es que Hermes lo haga como parte de su ciclo normal de trabajo.

Ejemplo de flujo:

1. Hermes modifica un handler de API.
2. Detecta que cambió una ruta, respuesta o contrato.
3. Ejecuta el escenario de Apidog indicado en AGENTS.md.
4. Lee el código de salida.
5. Si es 0, continúa.
6. Si no es 0, revisa la aserción fallida.
7. Corrige el código.
8. Vuelve a ejecutar el escenario.

Así, tus pruebas de API se integran en el mismo ciclo editar-probar-corregir que Hermes ya usa con pruebas unitarias.

Este es el patrón delegar-y-verificar:

• Hermes ejecuta el comando.
• Apidog valida el comportamiento real de la API.
• Tú verificas que Hermes respete el código de salida.

Para ejecuciones lentas, barridos grandes o escenarios con muchas iteraciones, la herramienta terminal de Hermes acepta background=true. Así puede iniciar el proceso, seguir trabajando y consultar el resultado después.

Para ampliar este patrón, consulta cómo usar agentes de IA para pruebas de API y el arnés de pruebas de IA de Apidog.

Opcional: conecta el servidor MCP de Apidog

La CLI permite a Hermes ejecutar pruebas. El servidor MCP de Apidog le permite leer tu especificación de API mientras escribe código.

Ambos se complementan:

• MCP entrega a Hermes el contrato de la API.
• La CLI verifica el comportamiento con escenarios reales.

Hermes soporta MCP de forma nativa. Edita:

~/.hermes/config.yaml

Añade una entrada bajo mcp_servers:

mcp_servers:
  apidog:
    command: "npx"
    args: ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"]
    env:
      APIDOG_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"

Después de guardar, recarga MCP dentro de Hermes:

/reload-mcp

O reinicia Hermes.

Al iniciar, Hermes descubre los servidores MCP y registra sus herramientas con el espacio de nombres:

mcp_apidog_<tool>

Así puede invocarlas durante su razonamiento normal.

Para la configuración completa, incluyendo ID de proyecto y token, consulta la guía del servidor MCP de Apidog. Para una versión empaquetada de este ciclo, consulta la guía de la CLI de Apidog con Claude Skills.

Del ciclo local a la CI

Cuando Hermes ya ejecuta el escenario localmente, has validado el mismo comando que puede usar tu pipeline.

La diferencia en CI es la autenticación:

• Localmente: la máquina ya inició sesión con apidog login.
• En CI: pasa el token como secreto enmascarado.

Puedes pedirle a Hermes que genere el paso de GitHub Actions:

Escribe un paso de GitHub Actions que instale apidog-cli y ejecute apidog run -t 605067 -e 1629989 -r junit, leyendo el token de acceso de un secreto del repositorio llamado APIDOG_ACCESS_TOKEN.

Un ejemplo de estructura sería:

- name: Install Apidog CLI
  run: npm install -g apidog-cli

- name: Run Apidog API tests
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
  run: |
    apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit

La mecánica completa de secretos, reporters y control por código de salida está en Apidog CLI en GitHub Actions.

El mismo comando queda disponible en tres lugares:

• Tu terminal.
• El ciclo de Hermes.
• La CI.

Y en todos los casos decide el mismo código de salida.

Problemas comunes

Hermes ignora AGENTS.md

Verifica que:

• El archivo se llama exactamente AGENTS.md o CLAUDE.md.
• Está en el directorio donde iniciaste Hermes.
• Reiniciaste la sesión después de crearlo o modificarlo.

Hermes solo sugiere el comando, pero no lo ejecuta

Hermes ejecuta comandos mediante terminal, normalmente detrás de una capa de aprobación.

Si queda pendiente, aprueba la ejecución. Si tu configuración bloquea comandos de terminal, permite al menos:

apidog run

apidog whoami indica que no estás autenticado

La sesión de Apidog se almacena en tu máquina, no dentro de Hermes.

Ejecuta tú mismo:

apidog login --with-token

Después pide a Hermes que confirme:

apidog whoami

No pegues tokens en el chat.

Hermes inventa un flag

Si ves un error como “unknown option”, Hermes probablemente adivinó un flag que no existe en tu versión.

Haz que ejecute:

apidog run --help

Luego actualiza AGENTS.md con el flag correcto.

Hermes informa éxito aunque el comando falló

Confía en el código de salida, no en el resumen.

Regla:

0     => éxito
!= 0  => fallo

Si la explicación de Hermes y el código de salida no coinciden, el código de salida gana.

Resumen

La integración de Hermes con Apidog requiere dos piezas:

1. Un bloque en AGENTS.md con el comando apidog run, las IDs correctas y la regla del código de salida.
2. El hábito de dejar que Hermes ejecute la CLI desde terminal y verificar el resultado.

Opcionalmente, puedes añadir el servidor MCP de Apidog en ~/.hermes/config.yaml para que Hermes lea tu especificación de API mientras codifica.

Tú sigues creando escenarios visualmente en Apidog. Hermes simplemente los ejecuta, interpreta el código de salida y corrige el código cuando una aserción falla.

Desde ahí, puedes llevar el mismo comando a tu pipeline con Apidog CLI en GitHub Actions o revisar todos los flags en la guía completa.

Preguntas frecuentes

¿Necesito un plugin de Hermes para usar la CLI de Apidog?

No. Hermes ejecuta comandos de shell con su herramienta terminal, así que puede llamar directamente a apidog run. La configuración específica de Hermes es el bloque en AGENTS.md y, opcionalmente, el servidor MCP.

¿Dónde pongo las instrucciones para enseñar a Hermes este flujo?

En AGENTS.md, en la raíz del repositorio. Hermes lee archivos de contexto como AGENTS.md y CLAUDE.md al iniciar la sesión y los usa como instrucciones del proyecto.

¿Cómo evito que Hermes simule una prueba pasada?

Pídele siempre el código de salida y verifica ese valor. apidog run solo devuelve 0 si todas las aserciones pasan. Si el texto de Hermes contradice el código de salida, confía en el código.

¿Cómo conecto el servidor MCP de Apidog a Hermes?

Añade una entrada mcp_servers en ~/.hermes/config.yaml con apidog-mcp-server, tu ID de proyecto y un token. Luego ejecuta /reload-mcp o reinicia Hermes. La guía del servidor MCP de Apidog cubre los detalles.

¿Funciona igual en otros agentes de codificación de IA?

La CLI funciona igual. Lo que cambia es cómo le das instrucciones al agente. Hermes lee AGENTS.md y ejecuta comandos mediante terminal; otros agentes usan sus propios archivos o mecanismos de contexto. La instalación y autenticación de la CLI siguen siendo las mismas, por lo que la guía de instalación también aplica.