DEV Community

Cover image for Apidog CLI: El cliente API en tu terminal
Roobia
Roobia

Posted on • Originally published at apidog.com

Apidog CLI: El cliente API en tu terminal

Tu espacio de trabajo API vive en una GUI, pero tu jornada laboral ocurre en una terminal. Cada cambio de contexto cuesta tiempo y concentración; en CI o durante una sesión con un agente de IA, la GUI ni siquiera es una opción. La CLI de Apidog lleva toda la plataforma Apidog—pruebas, endpoints, esquemas, entornos, mocks y documentación—al prompt de shell que ya utilizas.

Prueba Apidog hoy

La CLI de Apidog no es otro curl. Para lanzar un GET puntual y revisar el JSON, curl y HTTPie son suficientes; la recopilación de clientes REST de terminal y TUI cubre ese caso. La CLI de Apidog está pensada para trabajar con tu espacio de trabajo API: ejecuta escenarios de prueba, lee y actualiza el contrato API y mueve especificaciones dentro y fuera del proyecto mediante comandos que puede invocar un script o un agente.

Qué significa “reside en tu terminal”

Las herramientas HTTP de terminal gestionan una solicitud cada vez. La CLI de Apidog opera a nivel de proyecto y agrupa sus más de cuarenta comandos en cinco áreas:

Tarea Comandos
Ejecutar pruebas run, test-scenario, test-suite, test-case, test-data, test-report
Gestionar el contrato endpoint, schema, folder, common-parameter, response-component, security-scheme
Publicar documentación y mocks doc, docs-site, shared-doc, mock
Configurar e integrar environment, variables, vault, database-connection, websocket, socketio
Operar en equipo branch, merge-request, runner, scheduled-task, audit-log, import, export

Todos los comandos admiten --help, devuelven JSON estructurado y, en la mayoría de los casos, incluyen agentHints.nextSteps con los siguientes pasos recomendados. Esto permite que una persona o un agente continúe el flujo sin tener que memorizar toda la CLI.

Instala la CLI

La CLI se distribuye como el paquete npm apidog-cli y funciona en macOS, Linux y Windows. Requiere Node.js 16 o posterior.

npm install -g apidog-cli
apidog --version
Enter fullscreen mode Exit fullscreen mode

Inicia sesión con un token de acceso API. Puedes obtenerlo en la aplicación Apidog desde tu avatar → Configuración de la cuenta → Token de Acceso API.

apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

El token se guarda en ~/.apidog/config.toml. No lo incluyas en repositorios ni en los registros de CI. En una tubería, utiliza un secreto y pásalo mediante --access-token:

apidog run \
  --access-token "$APIDOG_TOKEN" \
  -t <scenario_id> \
  -e <env_id> \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Estas banderas globales cubren la mayoría de los casos:

  • --project: selecciona el proyecto.
  • --branch: selecciona la rama.
  • --access-token: sustituye la sesión guardada.
  • --api-base-url: apunta a una implementación de Apidog autoalojada.

Consulta la guía de autenticación de la CLI de Apidog para configurar tokens en CI.

Ejecuta las pruebas creadas visualmente

El flujo principal es crear un escenario de prueba en el editor visual de Apidog y ejecutarlo desde cualquier entorno con shell. Un escenario puede incluir:

  • Solicitudes encadenadas.
  • Variables extraídas de una respuesta y reutilizadas en la siguiente.
  • Aserciones sobre el estado HTTP y el cuerpo.
  • Datos de prueba desde archivos CSV o JSON.

En la pestaña CI/CD del escenario encontrarás el comando con los identificadores correspondientes:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

El proceso termina con código 0 cuando todas las aserciones pasan y con un código distinto de cero cuando alguna falla. Por eso puedes integrarlo directamente en CI sin añadir lógica adicional.

Para ejecutar el mismo escenario en distintos entornos, cambia -e:

apidog run -t <scenario_id> -e <development_env_id> -r cli
apidog run -t <scenario_id> -e <staging_env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

También puedes proporcionar un archivo CSV o JSON para repetir el escenario con cada fila. Este es el flujo de testing impulsado por datos sin duplicar pasos. Si partes desde cero, sigue el tutorial paso a paso de REST API.

Genera informes para CI

La CLI admite cuatro formatos de informe:

  • cli: muestra los resultados paso a paso en la terminal.
  • html: genera un informe HTML.
  • json: genera datos estructurados.
  • junit: genera resultados compatibles con paneles de CI.

Los formatos de archivo se guardan en apidog-reports/. Puedes combinarlos:

apidog run \
  -t <scenario_id> \
  -e <env_id> \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

La guía de informes de prueba muestra el contenido de cada formato.

Si las pruebas no deben depender de un portátil, los comandos runner y scheduled-task permiten gestionar runners autoalojados y ejecuciones programadas, la misma maquinaria utilizada por las pruebas API programadas en Apidog.

Gestiona el contrato API desde la terminal

La CLI que ejecuta tus pruebas también puede consultar y modificar la definición de tu API:

apidog endpoint list --project <project_id>
apidog schema get <schema_id>
apidog environment list
apidog mock list
Enter fullscreen mode Exit fullscreen mode

Puedes consultar y editar endpoints, esquemas de datos, carpetas, entornos, variables, esquemas de seguridad y componentes reutilizables.

El comando mock gestiona las expectativas de simulación y los pares fijos de solicitud y respuesta que devuelve el servidor mock. Los comandos doc y docs-site gestionan la documentación publicada. Los endpoints de WebSocket y Socket.IO tienen sus propios grupos, mientras que database-connection cubre las configuraciones de base de datos utilizadas por los escenarios de prueba.

Importa y exporta especificaciones

La CLI admite OpenAPI 3.x, Swagger 2.0 y colecciones de Postman. Esto permite automatizar migraciones y sincronizaciones desde scripts:

apidog import openapi.json --project <project_id>
apidog export --format openapi
Enter fullscreen mode Exit fullscreen mode

Puedes extraer una especificación de otro sistema, importarla en Apidog y versionar el intercambio junto con el resto del proyecto. Consulta la especificación de OpenAPI para conocer el estándar utilizado por gran parte del ecosistema.

Usa la CLI con agentes de IA

Las versiones de 2026 de la CLI están orientadas a que un agente de codificación pueda operar un espacio de trabajo API de forma controlada. Cuatro capacidades son especialmente útiles.

1. Salida estructurada

Cada comando devuelve JSON que un agente puede analizar. Además, agentHints.nextSteps sugiere qué ejecutar después, incluso cuando se produce un error.

2. Esquemas de entrada y validación

Los comandos cli-schema exponen la estructura JSON que esperan las operaciones de escritura:

apidog cli-schema list
apidog cli-schema get <command>
apidog cli-schema validate <payload.json>
Enter fullscreen mode Exit fullscreen mode

El flujo recomendado para escribir de forma segura es:

  1. Obtener el esquema del comando.
  2. Generar el JSON.
  3. Validar la carga útil.
  4. Ejecutar create o update.

3. Habilidad empaquetada

El comando skill proporciona el conocimiento operativo de la CLI en un formato que los agentes pueden cargar directamente. Esta es la razón detrás de la habilidad de la CLI de Apidog.

Según las mediciones descritas por Apidog, los agentes que trabajan mediante el esquema de la CLI utilizaron aproximadamente un 30 % menos de llamadas a herramientas y un 25 % menos de tokens que los agentes que generaban cargas útiles por inferencia. Los datos están detallados en este análisis.

4. Puertas de permiso y ramas de IA

De forma predeterminada, las escrituras en una rama iniciadas por IA están bloqueadas hasta que un humano habilita los Permisos de Edición de IA Externa. Esta opción está disponible en el cliente Apidog 2.8.32 o posterior, dentro de Configuración del Proyecto → Configuración de Funciones → Configuración de Funciones de IA.

Otra opción es utilizar una rama de IA. El agente puede importar los recursos necesarios, realizar cambios aislados y devolverlos como una solicitud de fusión para revisión humana. Las ramas de IA sin cambios se autoarchivan después de 24 horas. Así, el contrato API sigue siendo revisable aunque el primer borrador lo genere un agente.

Límites de la CLI de Apidog

Elegir una herramienta resulta más sencillo cuando sus límites están claros.

No es un cliente HTTP interactivo

No está diseñada para escribir un POST ad hoc y mostrar una respuesta con formato. Para ese trabajo, utiliza curl, HTTPie o un cliente TUI.

No es de código abierto

El paquete es propietario, npm es el único canal de instalación y cualquier operación más allá de --help requiere una cuenta de Apidog. El nivel gratuito cubre el flujo de trabajo descrito aquí. Si necesitas una licencia auditable, un runner de código abierto puede ser una opción más adecuada.

No es independiente de Apidog

La CLI es la interfaz de terminal de la plataforma. Los escenarios, endpoints y entornos viven en tu proyecto de Apidog, no en archivos locales. Esa dependencia proporciona una fuente única de verdad para el diseño, las pruebas, los mocks y la documentación.

Dónde encaja frente a otras herramientas

La principal diferencia está en dónde se crean las pruebas:

  • Newman y la CLI de Postman ejecutan colecciones creadas en Postman.
  • Hurl y Bruno ejecutan pruebas definidas como archivos de texto.
  • La CLI de Apidog ejecuta escenarios creados en un editor visual que también contiene el contrato, los mocks y la documentación.

La comparación entre Apidog CLI y Newman profundiza en esas diferencias. También puedes consultar la recopilación de herramientas de prueba de API basadas en terminal.

Una configuración práctica para muchos equipos es:

  1. Utilizar curl o xh para comprobaciones rápidas.
  2. Crear escenarios reutilizables en Apidog.
  3. Ejecutarlos en CI con apidog run.
  4. Publicar informes JUnit como artefactos de la tubería.

El tutorial de GitHub Actions incluye una tubería lista para adaptar.

Preguntas frecuentes

¿Es gratuita la CLI de Apidog?

Sí. El paquete se instala gratuitamente desde npm y el nivel gratuito de Apidog cubre la creación y ejecución de escenarios mediante la CLI. Los planes de pago añaden características para equipos, no el acceso básico a la CLI.

¿Sustituye a curl o HTTPie?

No. Esas herramientas envían solicitudes ad hoc; la CLI de Apidog ejecuta escenarios guardados y gestiona recursos del proyecto. Puedes utilizar ambas categorías según el caso.

¿Puede ejecutarse sin interfaz gráfica en CI?

Sí. Utiliza --access-token con un secreto de CI, ejecuta apidog run con el ID del escenario y condiciona la construcción al código de salida. El runner no necesita la aplicación de escritorio.

¿Qué formatos puede importar y exportar?

OpenAPI 3.x, Swagger 2.0 y colecciones de Postman, en ambas direcciones.

¿Cómo utilizan los agentes de IA la CLI de forma segura?

Mediante el flujo esquema-validación-escritura y las puertas de permiso. cli-schema validate detecta cargas útiles mal formadas antes de aplicarlas, mientras que las ramas de IA mantienen los cambios aislados hasta que una persona los fusiona. Consulta cómo usar la CLI de Apidog en Claude Code para ver un ejemplo.

La terminal es donde ya ejecutas tus pruebas y donde trabajan tus agentes. Instala la CLI desde npm y ejecuta un escenario de principio a fin. Puedes descargar Apidog y consultar la referencia completa de la CLI de Apidog cuando necesites ir más allá de run.

Top comments (0)