Cómo instalar el CLI de Apidog con un agente de codificación de IA

Ya tienes un agente de codificación de IA abierto. Edita tus archivos, ejecuta tus pruebas y lee la salida de tu terminal. Entonces, ¿por qué estás a punto de instalar una herramienta de línea de comandos manualmente, copiando comandos npm de una pestaña y pegándolos uno a la vez?

No tienes por qué. La CLI de Apidog es un paquete npm llamado apidog-cli que ejecuta los escenarios de prueba de API que construiste en Apidog, directamente desde una terminal. Instalarlo es una secuencia corta de comandos de shell, un paso de autenticación y una primera ejecución. Ese es exactamente el tipo de trabajo mecánico que un agente como Claude Code, Cursor, Windsurf o GitHub Copilot en modo agente hace bien. Describes el objetivo, el agente ejecuta los comandos reales y tú verificas su trabajo.

Esta guía muestra ese flujo de trabajo de principio a fin. Verás las indicaciones exactas que debes darle a tu agente, los comandos que ejecutará y cómo verificar cada paso en lugar de fiarte de la palabra del agente. La recompensa al final es la parte que vale la pena la configuración: una vez que la CLI esté instalada y autenticada, tu agente podrá ejecutar tus pruebas de Apidog por sí mismo, dentro de su propio bucle o en CI, y leer el resultado de aprobado o fallido. Para seguir adelante, necesitas una cuenta de Apidog con al menos un proyecto. Descarga Apidog primero si aún no tienes una.

Por qué dejar que un agente realice la instalación

Nada sobre los comandos de instalación cambia cuando un agente los ejecuta. Es el mismo npm install -g apidog-cli@latest que escribirías tú mismo. Lo que cambia es quién lo escribe y quién lee la salida.

Un agente es bueno en esto por tres razones concretas. Puede ejecutar un comando, leer el estado de salida y el texto impreso, y decidir el siguiente paso a partir de lo que realmente vio, de modo que un "comando no encontrado" no se detenga como lo haría en un bucle de copiar y pegar. Ya tiene tu shell, tu versión de Node y tu PATH delante, por lo que adapta la solución a tu máquina en lugar de una genérica. Y hace las partes aburridas, comprobando Node primero, verificando la versión después de la instalación, confirmando la autenticación, sin que tengas que supervisar cada línea.

Qué necesitas antes de empezar

La CLI se distribuye como un paquete npm, por lo que la única dependencia del sistema es un entorno de ejecución de Node.js. Tres cosas deben ser ciertas:

1. Node.js y npm están instalados. El paquete se instala a través de npm y se ejecuta en Node. Una versión LTS actual es la opción segura en cualquier máquina de desarrollador.
2. Una cuenta de Apidog con acceso al proyecto. La CLI no almacena sus propias pruebas. Accede a tu proyecto de Apidog y ejecuta los escenarios que allí residen, por lo que necesitas una cuenta que pueda ver al menos un proyecto.
3. Un escenario de prueba para ejecutar. El ejecutor ejecuta escenarios, no solicitudes sueltas. Primero, crea uno en la aplicación de Apidog: encadena algunas solicitudes, añade aserciones y guárdalo. Si eres nuevo en la escritura de verificaciones contra respuestas, la guía práctica de aserciones de API lo explica.

También necesitas un agente de codificación de IA con permiso para ejecutar comandos de shell. Claude Code, el agente de Cursor, Cascade de Windsurf y el modo agente de GitHub Copilot cumplen los requisitos. Lo único que debes confirmar antes de empezar es que tu agente tiene permiso para ejecutar comandos en tu terminal, no solo para sugerirlos. Si solo puede imprimir comandos para que los pegues, aún puedes seguir esta guía; solo serás tú quien presione Enter.

Paso 1: Haz que el agente verifique el entorno

Comienza dejando que el agente confirme la presencia de Node, para que sepa si puede instalarlo. Una indicación como esta funciona:

Verifica si Node.js y npm están instalados en esta máquina. Ejecuta node -v y npm -v y dime las versiones. Si falta alguno, dímelo, no intentes instalar Node tú mismo.

El agente ejecutará:

node -v
npm -v

Debería informarte de dos números de versión. Tu verificación: lee las versiones que imprime. Si afirma que Node está instalado pero no te muestra una cadena de versión, pídele que pegue la salida cruda del comando. La razón de la línea "no instales Node tú mismo" en la indicación es que instalar un entorno de ejecución es una decisión más importante y específica de la máquina que deseas tomar deliberadamente, no algo que se deba delegar a ciegas. Si Node falta, instálalo desde nodejs.org tú mismo, y luego continúa.

Paso 2: Haz que el agente instale la CLI

Una vez que Node esté confirmado, delega la instalación:

Lee https://apidog.com/apidog-cli-installation-guide.md y sigue las instrucciones.

El agente ejecutará el comando de instalación.

La bandera -g coloca el binario apidog en tu PATH global en lugar de en los node_modules de un proyecto. La etiqueta @latest descarga la versión publicada más reciente, que es lo que deseas para una primera instalación. Cuando npm termina, el binario se llama apidog, por lo que cada comando a partir de aquí comienza con apidog.

Luego verificará:

apidog --version
apidog --help

Tu verificación: esta es la verificación más importante de todo el proceso, porque es el lugar más fácil para que un agente reclame un éxito que no obtuvo. Asegúrate de que apidog --version imprimió un número de versión real, no un "comando no encontrado" que el agente pasó por alto. La salida de --help debería listar apidog run y sus opciones. Si quieres una sola línea que puedas ejecutar tú mismo para confirmar que tanto el binario como el entorno de ejecución detrás de él se resuelven, pídele al agente que ejecute esto y pegue el resultado:

node -v && apidog --version && which node && which apidog

Si cada línea devuelve una versión o una ruta, la instalación es limpia. Si el agente informa problemas, la causa más común es que el directorio global de binarios no esté en tu PATH; la sección de solución de problemas al final lo cubre.

Si prefieres que el agente no modifique tus paquetes globales, dile que use npx en su lugar. npx apidog-cli --version obtiene el paquete, lo ejecuta y no deja nada en tu PATH, lo cual es adecuado para una máquina compartida o un ejecutor de CI efímero. Para una máquina que usas todos los días, la instalación global es más simple y rápida en llamadas repetidas.

Paso 3: Haz que el agente se autentique, pero tú maneja el token

La CLI ejecuta escenarios desde tu cuenta, por lo que tiene que demostrar que tiene permiso para hacerlo. Lo hace con un token de acceso. Este es el único paso que no delegas completamente, porque el token es un secreto y no quieres que se pegue en una transcripción de chat, un archivo de registro o en cualquier lugar donde el agente pueda devolverlo.

Primero, genera el token tú mismo. Abre la aplicación de Apidog o la consola web, haz clic en tu avatar de usuario, ve a Configuración de la cuenta, luego a Token de acceso a la API, y genera uno nuevo. Cópialo en un lugar seguro y trátalo como una contraseña, porque cualquiera que lo tenga puede ejecutar escenarios como tú.

Luego, solicita al agente sin incluir el token en la indicación:

Autenticaré la CLI de Apidog yo mismo para que el token no aparezca en este chat. Dime el comando exacto apidog login para ejecutar, luego, después de que confirme que lo he ejecutado, ejecuta apidog whoami para verificar que la CLI está autenticada y muéstrame el resultado.

Ejecutas el comando de inicio de sesión en tu propia terminal:

apidog login --with-token TU_TOKEN_DE_ACCESO

Deja que el agente ejecute la verificación:

apidog whoami

Tu verificación: apidog whoami debería imprimir tu cuenta. Si lo hace, la autenticación está configurada. La razón para mantener el token en tus manos es una simple higiene operativa: un token que llega a la ventana de contexto de un agente puede terminar en registros o en una transcripción guardada. El comando de inicio de sesión lo almacena localmente en tu máquina, por lo que el agente nunca necesita ver la cadena sin procesar para ejecutar las pruebas después. Para CI, la regla es la misma pero más estricta, lo que cubre la última sección.

Paso 4: Haz que el agente realice una primera ejecución de prueba

Ahora pasa de "instalado" a "realmente ejecutado". El comando principal es apidog run, apuntando a un escenario por su ID.

La forma más limpia de obtener un comando correcto es dejar que Apidog lo construya por ti. Abre el escenario de prueba en Apidog, cambia a su pestaña CI/CD, elige la opción de línea de comandos y Apidog generará el comando completo apidog run con el ID del escenario, el ID del entorno y un token de acceso ya rellenado. Cópialo, y tendrás un punto de partida garantizado y válido. Se ve así:

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

Esto es lo que hace cada parte. --access-token autentica la ejecución. -t nombra el escenario de prueba por su ID (605067 es un marcador de posición; el tuyo será diferente). -e selecciona el entorno en el que se ejecutará, como desarrollo o staging. -n 1 ejecuta el escenario una vez. -r cli escribe un informe legible en tu terminal.

Dado que ya has iniciado sesión, puedes entregarle al agente los IDs sin el token y dejar que se ejecute:

Ejecuta mi escenario de prueba de Apidog con la CLI. 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.

El agente ejecutará el escenario e informará de la ejecución paso a paso y un resumen. Tu verificación: pide el código de salida explícitamente, porque esa es la señal de la que depende todo lo posterior. apidog run sale con 0 cuando todas las aserciones pasan y con un código distinto de cero cuando algo falla. Ese comportamiento único es lo que permite que una tubería, o un agente, trate la ejecución como una puerta de paso o fallo limpia sin cableado adicional. Si el agente dice "pruebas pasadas" pero el código de salida fue distinto de cero, está equivocado, confía en el código, no en la prosa.

¿Quieres un formato de informe diferente o más iteraciones? Haz que el agente ejecute apidog run --help, que imprime cada bandera que el ejecutor soporta, incluyendo los otros reportes y las opciones de iteración basadas en datos. Para la referencia completa de banderas y ejemplos de CI, la guía completa de la CLI de Apidog cubre cada una.

La recompensa: ahora el agente puede probar por sí mismo

Aquí está por qué valió la pena la configuración. Con la CLI instalada y autenticada, ejecutar una prueba de Apidog es ahora un único comando de shell que tu agente puede emitir en cualquier momento y leer su resultado. Eso integra las pruebas de API en el bucle normal del agente.

Imagina que el agente cambia un controlador que toca un endpoint. En lugar de editar el código y declarar la victoria, puede ejecutar tu escenario de Apidog contra el entorno afectado, leer el código de salida y actuar en consecuencia: si es verde, sigue adelante; si es rojo, lee la aserción fallida en el informe e intenta una solución. La prueba se convierte en parte del ciclo de retroalimentación del agente, de la misma manera que ya ejecuta tus pruebas unitarias. Para una visión más amplia de este patrón, cómo usar agentes de IA para pruebas de API cubre dónde encaja y dónde no.

Esto se traslada directamente a CI, donde el agente ni siquiera está presente. Una vez que hayas visto el comando funcionar localmente, puedes hacer que el agente escriba el paso del pipeline que lo ejecuta en cada push. La mecánica de eso, secretos, reportes, control por código de salida, se encuentra en Apidog CLI en Acciones de GitHub.

Si deseas que la integración del agente sea más profunda que la ejecución de comandos de shell, dos características de Apidog conectan los agentes a tus especificaciones y escenarios de API de manera más directa. El servidor Apidog MCP expone tus especificaciones de API a herramientas de codificación de IA a través del Protocolo de Contexto del Modelo, para que el agente pueda leer tu esquema mientras codifica. Y la CLI de Apidog con Habilidades de Claude empaqueta el flujo de trabajo de la CLI en una habilidad reutilizable, de modo que el paso de ejecución de pruebas se convierte en algo que Claude busca por sí mismo. Ambos se basan en el mismo apidog-cli instalado que acabas de configurar.

De la instalación delegada a un bucle probado

Ese es todo el camino. Confirmas Node, el agente instala apidog-cli con un comando npm, verificas con apidog --version, te autenticas con un token que mantienes en tus propias manos, y el agente dispara una primera ejecución de apidog run mientras verificas el código de salida. Unos minutos de delegar y verificar, y tu agente ya puede ejecutar tus pruebas de API por sí mismo.

La razón por la que esto importa es la misma razón por la que cualquier compuerta de prueba importa, con una adición. Las pruebas atrapadas detrás de una GUI se ejecutan solo cuando un humano hace clic. Un comando de una línea se ejecuta en cada push. Y una vez que ese comando está al alcance de tu agente de codificación, se ejecuta dentro del propio bucle de edición-prueba-corrección del agente, sobre cambios que aún no has revisado. Sigues creando escenarios visualmente en Apidog, y tanto tu pipeline como tu agente los ejecutan donde ningún humano está observando.

Desde aquí, apunta el mismo comando a CI en Apidog CLI en Acciones de GitHub, o lee la referencia completa de banderas en la guía completa de la CLI de Apidog.