Diseño de una CLI para agentes de IA: JSON, códigos de salida y espera
El diseño de una CLI para agentes de IA requiere JSON estructurado, códigos de salida reales, espera hasta estados terminales, errores estables y confirmaciones seguras para la automatización en producción.
Una CLI para agentes de IA no es simplemente una herramienta de línea de comandos para humanos que también puede invocarse desde un modelo. Es un protocolo operativo. El agente necesita entradas deterministas, salidas estructuradas, códigos de salida significativos, categorías de error estables y una forma de esperar hasta que la infraestructura asíncrona alcance un estado final.
Sin ese contrato, el agente se ve obligado a inferir el éxito a partir de frases como «el despliegue ha comenzado». Esa inferencia es peligrosa, porque una solicitud aceptada puede fallar más adelante durante el build, las comprobaciones de salud, el arranque del contenedor o el cambio de tráfico.
¿Por qué es peligroso dar por hecho que un despliegue ha tenido éxito?
La mayoría de las operaciones de infraestructura son asíncronas. Una API puede aceptar un despliegue y devolver un ID en milisegundos, mientras que el build real tarda varios minutos. Si un agente informa de éxito en el momento de la aceptación, todos los pasos posteriores se basan en una premisa falsa.
Considera la diferencia:
| Evento | Lo que demuestra | Lo que no demuestra |
|---|---|---|
| Solicitud aceptada | La plataforma entendió la solicitud | Que el código se haya compilado |
| Build completado | Se creó una imagen o un artefacto | Que la aplicación se haya iniciado |
| Comprobación de salud superada | La nueva instancia respondió como era necesario | Que los flujos de negocio funcionen |
| Tráfico cambiado | La release pasó a estar activa | Que vaya a mantenerse saludable |
| Observación de uptime | El servicio sigue siendo accesible | Que todas las funcionalidades sean correctas |
Un humano puede percibir la diferencia en un dashboard. Un agente que opera mediante texto necesita que esta diferencia esté codificada en la interfaz.
El contrato de comandos de Dockup separa la puesta en cola de la finalización. Un deploy sin --wait devuelve el resultado inmediatamente con waited:false; un deploy con --wait se bloquea hasta alcanzar el éxito, un fallo o un timeout:
dockup deploy production/api --wait --json
El timeout predeterminado es de 900 segundos. El comando termina con 0 únicamente después de alcanzar un estado terminal correcto. Termina con un valor distinto de cero y deploy_failed o deploy_timeout cuando el resultado no es satisfactorio.
¿Qué aporta una CLI con JSON estructurado a un agente de IA?
El JSON estructurado sustituye la interpretación de prosa por campos con nombres. El agente puede localizar directamente status, deploymentId, target o code, sin depender de la puntuación, el color, el ancho de las columnas o la redacción.
Un resultado correcto puede consumirse como datos:
{
"ok": true,
"target": "production/api",
"deploymentId": "dep_123",
"waited": true,
"status": "success",
"durationMs": 142381,
"url": "https://api.dockup.tech"
}
Los errores utilizan la misma estructura de transporte:
{
"ok": false,
"error": "Deployment failed",
"code": "deploy_failed"
}
La regla de diseño importante es que el JSON se escriba en stdout, mientras que las advertencias que no deben corromper el parseo se envíen a stderr. Los logs en modo follow utilizan NDJSON (un objeto JSON por línea), de modo que quien realiza la llamada pueda procesar el flujo de forma incremental sin esperar a un único array enorme.
Dockup aplica --json a todos sus comandos. Con 135 comandos, exigir que un agente infiera los flags de memoria sería frágil. La referencia de la CLI y la skill incluida proporcionan las instrucciones de comandos alineadas con la versión que debe seguir el agente.
La propiedad de diseño importante no es el descubrimiento ingenioso. Es que el agente reciba instrucciones operativas actuales y estructuradas, y no invente un flag a partir de un prompt antiguo.
¿Cómo deben controlar los códigos de salida reales la automatización de despliegues?
El código de salida del sistema operativo es la señal de éxito más portable disponible para shell scripts, runners de CI y agentes de programación. El código 0 significa que el comando logró el resultado definido. Un código distinto de cero significa que quien realiza la llamada debe elegir entre la recuperación, la escalación o la terminación.
Este fragmento de shell es deliberadamente sencillo:
if dockup deploy production/api --wait --json > result.json; then
echo "deployment reached success"
else
dockup logs production/api --build --json
exit 1
fi
No busca la palabra «success» en stdout. Tampoco asume que una respuesta HTTP 202 implique que producción esté lista. Delega la definición del éxito en la CLI y propaga el fallo al proceso principal.
Los códigos de salida reales son igualmente importantes para comandos one-shot dentro de un contenedor. El comando PRO exec de Dockup devuelve stdout, stderr y el código de salida real del comando:
dockup exec "npm run migrate" \
-s production/api \
--json
Por tanto, un agente puede distinguir entre una migración completada y un comando que simplemente se ha iniciado. Este es un principio fundamental de las barreras de protección para agentes de IA en producción.
¿Cómo sustituye la espera hasta un estado terminal al polling frágil?
Los bucles de polling escritos a mano introducen decisiones de política ocultas: cada cuánto hacer polling, qué estados son terminales, cuánto tiempo esperar, si un error de red transitorio debe reiniciar el temporizador y qué hacer cuando un contenedor se reinicia.
Es especialmente probable que un agente se equivoque con estas decisiones porque puede no conocer la máquina de estados completa de la plataforma. La plataforma debería encargarse de la semántica de espera.
Dockup ofrece dos patrones útiles:
dockup deploy production/api --wait --timeout 1800 --json
dockup push --json
deploy --wait espera de forma explícita. push espera de forma predeterminada después de hacer push y activar la release; --no-wait permite omitir esa espera. Ambos devuelven un código de salida que refleja el resultado terminal.
El seguimiento de logs aplica la misma idea:
dockup logs production/api --build -f --json
El flujo termina cuando el build alcanza el éxito o el fallo. Un objeto NDJSON final indica done:true, y un build fallido termina con un código distinto de cero. Quien realiza la llamada no necesita una segunda implementación de polling.
Para comprobar la disponibilidad de la aplicación después del despliegue, el comando uptime de Dockup devuelve comprobaciones por minuto, el tiempo medio de respuesta y el p95:
dockup uptime production/api --hours 24 --json
La espera y la monitorización son conceptos distintos. --wait responde si este despliegue alcanzó un resultado terminal; uptime indica cómo se comportó el servicio en ejecución a lo largo del tiempo.
¿Qué códigos de error debería entender un agente?
Las categorías de error estables permiten que un agente lleve a cabo una acción acotada sin interpretar cada mensaje posible. Dockup expone códigos como los siguientes:
| Código de error | Significado | Respuesta segura del agente |
|---|---|---|
not_logged_in | No hay ningún token utilizable | Detenerse y solicitar autenticación |
not_linked | No existe ningún destino .dockup para push | Resolver el destino o pasarlo explícitamente |
no_target | No se ha podido identificar el servicio | Ejecutar services --json |
needs_confirm | La acción destructiva no tiene aprobación | Preguntar a un humano |
deploy_trigger_failed | No se ha podido iniciar el despliegue | Informar del error de la API |
deploy_failed | El build o el despliegue han terminado con un fallo | Leer los logs del build |
deploy_timeout | Sigue en ejecución después del límite de espera | Informar de la incertidumbre o ampliar el límite de forma deliberada |
El mensaje de error sigue siendo un contexto útil, pero el código dirige la primera decisión. Esto hace que la automatización sea resistente a cambios en la redacción o la localización.
La confirmación también forma parte del protocolo. Un comando destructivo no debería ejecutarse silenciosamente porque quien lo invoca no sea interactivo. Dockup rechaza estas operaciones sin --yes y devuelve needs_confirm. Un agente autónomo ve una solicitud de confirmación, no una barrera que deba eludirse.
El modelo de seguridad se analiza con más detalle en prácticas recomendadas de seguridad.
¿Cuál es el contrato mínimo de una CLI preparada para producción?
Una CLI para agentes de IA preparada para producción debería cumplir un contrato pequeño, pero estricto:
- Todas las operaciones de lectura y escritura tienen una salida legible por máquinas.
- Los fallos producen un código de salida distinto de cero.
- Las mutaciones asíncronas pueden esperar hasta un estado terminal documentado.
- Los valores secretos nunca se devuelven mediante comandos de lectura.
- Las acciones destructivas requieren una confirmación explícita.
- Los errores tienen códigos estables adecuados para ramificar la lógica.
- El paquete de la CLI y las instrucciones del agente se mantienen alineados con la versión.
- Las mutaciones se registran en un audit trail.
La skill de Dockup convierte estas reglas en el comportamiento predeterminado para Claude Code y Codex. Indica al agente que use JSON, se autentique con DOCKUP_TOKEN, descubra los destinos exactos, haga deploy con --wait, proteja las credenciales y se detenga ante needs_confirm.
Compara este modelo con los conceptos más amplios de agent skills frente a MCP. Una skill proporciona conocimiento operativo; la CLI sigue siendo la interfaz ejecutable cuyos códigos de salida y cuya salida definen la verdad.
Una matriz de pruebas para un comando orientado a agentes
Antes de exponer cualquier comando de infraestructura a un agente, prueba algo más que el happy path:
| Prueba | Comportamiento esperado |
|---|---|
| Solicitud válida | Resultado JSON y salida 0 |
| Token no válido | Código de autenticación estable y salida distinta de cero |
| Destino desconocido | Código de destino estable y ninguna mutación |
| Deploy de larga duración | Espera hasta el estado terminal o el timeout |
| Deploy fallido | Salida distinta de cero más un ID de despliegue que permita diagnosticar |
| Falta de aprobación destructiva | needs_confirm, sin eliminación |
| Lectura de un secreto | Metadatos de la clave visibles y valor oculto |
| Advertencia durante la salida JSON | Advertencia en stderr y JSON válido en stdout |
Esta matriz es más valiosa que un spinner de progreso pulido. El formato para humanos puede añadirse por encima; un contrato determinista para máquinas no puede reconstruirse después.
La documentación de la CLI de Dockup muestra los comandos concretos que sustentan este modelo, mientras que desarrollo con IA explica el cambio más amplio del uso manual de herramientas a los workflows dirigidos por agentes.
Trata la observabilidad como parte del contrato del comando
Una mutación orientada a agentes debería devolver identificadores que permitan investigar posteriormente. Una respuesta de despliegue necesita el destino y el ID del despliegue; una base de datos creada necesita un slug estable; un snapshot de un volumen necesita su ID de snapshot. Sin estas referencias, el agente puede describir un evento, pero no puede inspeccionarlo, reintentarlo o revertirlo de forma fiable.
El audit trail completa el contrato. La salida estructurada explica una invocación, mientras que los registros de auditoría conectan varias invocaciones a lo largo del tiempo. Juntos permiten a los operadores responder si el agente actuó sobre el recurso previsto y si un comando de recuperación posterior se refería al mismo evento de producción.
Mantén la interfaz sencilla
Una CLI para agentes de IA fiable no debería sorprender bajo condiciones de éxito, fallo, timeout o reintento.
Prueba final de la interfaz
La CLI para agentes de IA debe fallar con veracidad.
Lleva el workflow a producción
Prueba primero el contrato desde un shell: verifica el parseo de JSON, una salida correcta, un fallo forzado, un timeout y una operación destructiva bloqueada antes de delegar el acceso a producción.
npm install -g dockup-cli
dockup skill install
El primer comando instala la CLI. El segundo instala la skill de Dockup compatible con Claude Code y Codex. Empieza gratis en app.dockup.ai.
Preguntas frecuentes
¿Qué hace que una CLI sea adecuada para agentes de IA?
Necesita una salida estructurada, códigos de salida reales, espera hasta estados terminales, códigos de error estables, ocultación de secretos y confirmación explícita para las operaciones destructivas.
¿Por qué es mejor el JSON que la salida de una CLI con formato para humanos cuando la utilizan agentes?
El JSON proporciona nombres y tipos de campo estables. El agente no tiene que inferir el significado a partir de colores, tablas, puntuación o una redacción cambiante.
¿Por qué una solicitud de despliegue aceptada no equivale a un éxito?
La aceptación solo demuestra que la plataforma puso la operación en cola. El build, el arranque, la comprobación de salud y el cambio de tráfico posteriores todavía pueden fallar.
¿Cuál es el timeout de espera predeterminado de los despliegues de Dockup?
El timeout predeterminado de dockup deploy --wait es de 900 segundos y puede cambiarse con la opción documentada --timeout.
¿Cómo debería reaccionar un agente ante needs_confirm?
Debería detenerse y solicitar una aprobación explícita. El código significa que la acción solicitada es destructiva y se ha decidido no ejecutarla.