Cómo usar Apidog CLI en Cursor

El agente de Cursor ya edita archivos, ejecuta su terminal, lee la salida y corrige lo que rompió. El siguiente paso es integrar sus pruebas de API en ese ciclo: deje que Cursor ejecute sus escenarios reales de Apidog, lea el resultado (aprobado o fallido) y continúe. La pieza que lo hace funcionar es un ejecutor de línea de comandos que Cursor puede invocar.

Ese ejecutor es la CLI de Apidog, un paquete npm llamado apidog-cli. Ejecuta los escenarios de prueba que construyó visualmente en Apidog desde una terminal y sale con un código de estado sobre el que Cursor puede actuar. Esta guía cubre la mitad específica de Cursor: el archivo de reglas que enseña a Cursor su flujo de trabajo, la indicación que ejecuta una prueba, cómo la ejecución se integra en su ciclo de edición-prueba-corrección, y el servidor MCP opcional que entrega a Cursor su especificación de API mientras codifica.

Si la CLI aún no está instalada, comience con cómo instalar la CLI de Apidog con un agente de codificación de IA, que guía a Cursor a través de la instalación y autenticación. Vuelva una vez que apidog --version imprima un número. También necesita una cuenta de Apidog con al menos un escenario de prueba guardado. Descargue Apidog si no tiene uno.

Qué significa "usar la CLI en Cursor"

No hay un plugin de Apidog para Cursor, y no lo necesita. El Agente de Cursor ya ejecuta comandos de shell en la terminal de su proyecto. Por lo tanto, usar la CLI de Apidog en Cursor significa tres cosas:

1. Enseñe a Cursor el flujo de trabajo una sola vez con una regla de proyecto, para que conozca el comando, las banderas y que el código de salida es la fuente de verdad.
2. Haga que el Agente ejecute apidog run como un paso normal en su ciclo, como ejecuta sus pruebas unitarias.
3. Conecte opcionalmente el servidor Apidog MCP, para que Cursor pueda leer su especificación de API mientras escribe el código que esas pruebas verifican.

La regla es lo que le da esta forma específica para Cursor en lugar de una guía genérica de "abrir una terminal y escribir".

Paso 1: Añadir una regla de proyecto

Cursor lee las reglas del proyecto desde un directorio .cursor/rules en la raíz de su repositorio. Cada regla es un archivo .mdc con un pequeño bloque de metadatos (frontmatter), controlado por versiones junto con su código para que todo el equipo obtenga el mismo comportamiento.

Cree una de dos maneras: escriba /create-rule en el chat y describa lo que quiere, o abra Configuración de Cursor > Reglas, Comandos, haga clic en + Añadir Regla. De cualquier manera, obtendrá un archivo bajo .cursor/rules.

Guarde esto como .cursor/rules/apidog-cli.mdc:

---
description: Cómo ejecutar pruebas de API de Apidog desde la terminal
alwaysApply: false
---

# Ejecución de pruebas de API de Apidog

Este proyecto tiene escenarios de prueba de API en Apidog. Ejecútelos con el
apidog-cli, que está instalado globalmente y ya autenticado.

- El comando es `apidog run`. El binario es `apidog`.
- Ejecute un único escenario por ID: `apidog run -t  -e  -n 1 -r cli`
  - `-t` es el ID del escenario de prueba, `-e` es el ID del entorno.
  - `-n 1` lo ejecuta una vez. `-r cli` imprime un informe legible en la terminal.
- No pase `--access-token`. La autenticación se maneja con un `apidog login` previo.
- El código de salida es la fuente de verdad: `0` significa que todas las aserciones pasaron,
  no cero significa un fallo. Informe el código de salida, no solo un resumen.
- Si un indicador es desconocido, ejecute `apidog run --help` y use el indicador exacto de allí.
  Nunca adivine los nombres de los indicadores.
- Después de cambiar el código que afecta un endpoint, ejecute el escenario relevante
  y lea el resultado antes de afirmar que el cambio funciona.

El frontmatter importa. description más alwaysApply: false convierte esto en una regla de aplicación inteligente: Cursor la incluye cuando el chat trata sobre la ejecución de pruebas, en lugar de consumir contexto en cada conversación. Establezca alwaysApply: true para mantenerla siempre en el ámbito. Para limitarla a un tipo de archivo, elimine la descripción y añada una línea globs, y Cursor la adjuntará automáticamente cuando se abra un archivo coincidente.

El contenido hace el trabajo real. Fija la forma del comando, dice de dónde viene la autenticación y establece la línea que mantiene a un agente honesto: el código de salida prevalece sobre la prosa. Los agentes a veces leen un informe fallido y lo llaman "se ve bien". Escribir esa regla una vez significa que no tiene que corregirlo manualmente.

Paso 2: Obtener el comando de Apidog

Antes de pedirle al Agente que ejecute algo, obtenga un comando que sepa que funciona. No haga que Cursor adivine los IDs.

Abra su escenario de prueba en Apidog, cambie a su pestaña CI/CD y elija la opción de línea de comandos. Apidog construye el comando completo apidog run con el ID del escenario, el ID del entorno y un token de acceso ya rellenados:

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

605067 es el ID del escenario de prueba y 1629989 es el ID del entorno; los suyos serán diferentes. Dado que autenticó la CLI durante la instalación, elimine la parte --access-token y conserve los IDs. Ese es el comando que su regla le indicó a Cursor que usara.

Paso 3: Hacer que el Agente ejecute la prueba

Abra el Agente de Cursor (el modo de chat que ejecuta comandos de terminal, no la edición en línea). Con la regla establecida, la indicación es corta:

Ejecuta mi escenario de prueba de Apidog y muéstrame la salida completa y dime el código de salida.

Cursor propone el comando y, después de que usted lo apruebe, lo ejecuta en la terminal integrada:

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

Por defecto, Cursor pregunta antes de ejecutar un comando de terminal, por lo que verá exactamente lo que está a punto de ejecutar. Apruebe, y el Agente ejecutará el escenario, luego leerá la ejecución y un resumen.

Su verificación: mire el código de salida, no el resumen. apidog run sale con 0 cuando todas las aserciones pasan y con un valor distinto de cero cuando alguna falla. Ese comportamiento es la razón principal por la que esto funciona como una puerta de control, para CI y para el Agente. Si Cursor dice "pruebas pasadas" pero el código de salida no fue cero, está equivocado; confíe en el código. Este es el fallo exacto que previene la regla del Paso 1.

Para un formato de informe diferente o más iteraciones, haga que el Agente ejecute apidog run --help para que lea la lista real de indicadores para su versión instalada. La guía completa de la CLI de Apidog documenta cada indicador, incluidos los reporteros html, json y junit y la iteración basada en datos.

Paso 4: Leer el informe dentro de Cursor

El reportero -r cli imprime los resultados en la terminal que Cursor ya lee, lo que lo hace adecuado para el trabajo del Agente. El Agente ve las mismas líneas que usted: qué escenario se ejecutó, cada solicitud, cada aserción y el recuento final de aprobados o fallidos.

Cuando una ejecución falla (se "pone en rojo"), el informe nombra la aserción que falló, el valor esperado y lo que devolvió el endpoint. Dado que ese texto está en el contexto del Agente, continúe en el mismo chat:

El escenario falló. Lee la aserción fallida en el informe, encuentra el manejador que produce ese campo y propón una solución. Luego ejecuta el escenario de nuevo y muéstrame el nuevo código de salida.

Ahora la prueba es parte del ciclo. Cursor edita el manejador, vuelve a ejecutar apidog run, lee el nuevo código de salida y o bien continúa o lo intenta de nuevo. Sus comprobaciones de API viven en el mismo ciclo de edición-prueba-corrección que Cursor utiliza para las pruebas unitarias, excepto que estas se ejecutan contra endpoints reales. Para el patrón más amplio, cómo usar agentes de IA para pruebas de API cubre dónde encaja y dónde no.

Opcional: conectar el servidor Apidog MCP

La CLI permite a Cursor ejecutar sus pruebas. El servidor Apidog MCP permite a Cursor leer su especificación de API mientras escribe código. Ambos se complementan: el servidor MCP alimenta a Cursor con su esquema para que genere código que coincida con el contrato, y la CLI verifica ese código contra escenarios reales.

Cursor soporta servidores MCP a través de una configuración JSON. Coloque los servidores con ámbito de proyecto en .cursor/mcp.json en la raíz de su repositorio, o los globales en ~/.cursor/mcp.json. La estructura es un objeto mcpServers indexado por un nombre, cada uno con un command, un array de args y valores env opcionales:

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

Dos notas. MCP está restringido por un interruptor en algunas instalaciones, así que abra la Configuración de Cursor, busque la sección "Model Context Protocol" y confirme que el servidor Apidog está habilitado. Y si envía .cursor/mcp.json, no codifique el token; haga referencia a una variable de entorno. Para la configuración completa, incluyendo dónde obtener el ID del proyecto y el token, consulte la guía del servidor Apidog MCP. Para un flujo de trabajo empaquetado y reutilizable en lugar de conectarlo manualmente, la guía de la CLI de Apidog con habilidades de Claude muestra la versión basada en habilidades.

Del bucle local a CI

Una vez que Cursor haya ejecutado el escenario localmente y haya actuado según el código de salida, habrá validado el comando exacto que utilizará su pipeline. El salto a CI es pequeño: el mismo apidog run, con el token pasado como un secreto enmascarado en lugar de un inicio de sesión almacenado. Incluso puede pedirle a Cursor que escriba el paso, ya que conoce el comando de su regla:

La mecánica de ese paso (secretos, reporteros, control de código de salida) se encuentra en Apidog CLI en Acciones de GitHub. El mismo comando ahora se ejecuta en tres lugares: su terminal, el bucle del Agente de Cursor y CI, todos confiando en el mismo código de salida.

Problemas comunes

La regla no se aplica. Con description y alwaysApply: false, Cursor solo carga la regla cuando considera que el chat es relevante. Si una sesión de prueba no la está detectando, menciónela con @apidog-cli en el chat, o cambie a alwaysApply: true.

El Agente no puede ejecutar el comando. Si solo sugiere comandos en lugar de ejecutarlos, probablemente esté en modo de edición en lugar del Agente, o se perdió la solicitud de aprobación. Confirme que está en el chat del Agente y apruebe cuando Cursor lo solicite. Si las ejecuciones de terminal fallan por completo, suele ser el problema de PATH de apidog: command not found que cubre la guía de instalación.

apidog whoami muestra que no está autenticado. El inicio de sesión se guarda en su máquina, no en Cursor. Ejecute apidog login --with-token usted mismo con un token nuevo de Apidog, luego pida al Agente que confirme con apidog whoami. Mantenga el token fuera del chat.

Inventa un indicador. Si una ejecución falla con un error de "opción desconocida", el Agente adivinó un indicador que no existe en su versión. Pídale que ejecute apidog run --help y copie el indicador exacto.

Conclusión

La configuración de Cursor es un archivo y un hábito: una regla .cursor/rules/apidog-cli.mdc que fija el comando, la fuente de autenticación y la regla del código de salida, más el hábito de dejar que el Agente ejecute apidog run y verificar usted mismo el código de salida. Añada el servidor Apidog MCP y Cursor también podrá leer su especificación mientras codifica.

Usted sigue creando escenarios visualmente en Apidog; Cursor simplemente los ejecuta. A partir de aquí, apunte el mismo comando a su pipeline con Apidog CLI en Acciones de GitHub, o lea la referencia completa de indicadores en la guía completa de la CLI de Apidog.