Guías modernas para CLIs bien hechas

Las terminales volvieron a ocupar un lugar central. No solo para quienes administran servidores o viven en bash todo el día, sino también para personas que usan herramientas de desarrollo, automatización local, build systems y agentes que ejecutan tareas por ti. Si una CLI está mal diseñada, te hace perder tiempo desde el primer comando: mensajes ambiguos, flags inconsistentes, errores que no dicen nada y salidas que no se pueden leer ni parsear.

Por eso las Command Line Interface Guidelines llegan en un momento útil. No hablan de estética ni de nostalgia por la consola; hablan de cómo hacer que una CLI sea clara, predecible y usable tanto para humanos como para scripts. La referencia oficial está en https://clig.dev/ y vale la pena leerla con calma si construyes herramientas internas, SDKs, wrappers o productos que se operan desde terminal.

Por qué una CLI moderna ya no es opcional

Hoy una CLI no compite solo contra otras CLIs. Compite contra interfaces web, extensiones de editor, automatizaciones y agentes que necesitan una superficie de control simple. Si tu herramienta vive en la terminal, el usuario espera tres cosas muy concretas: que aprenda rápido, que falle con mensajes útiles y que no rompa flujos existentes cuando la actualizas.

Eso cambia el estándar. Antes bastaba con que un comando “funcionara”. Ahora necesitas consistencia de comportamiento, compatibilidad con scripts y una salida pensada para ser leída por personas y máquinas. Si un equipo en Bogotá, Quito o Ciudad de México integra tu CLI en CI, no quiere descubrir a medianoche que cambiaste un formato de salida sin aviso.

Las guías modernas ayudan a ordenar ese caos. No te dicen que todas las herramientas deben verse igual, pero sí que ciertas decisiones son más sanas que otras: nombres predecibles, errores en stderr, códigos de salida consistentes, flags explícitas y formatos estables. Eso reduce soporte, evita tickets repetidos y hace que tu producto se sienta profesional desde el primer uso.

Qué cambia cuando piensas en humanos y scripts al mismo tiempo

Una CLI bien hecha no solo se entiende a ojo. También debe ser fácil de automatizar. Eso significa que la salida por defecto puede ser amigable, pero debe existir una forma estable de pedir JSON, texto plano o un formato pensado para máquinas. Si mezclas logs, progreso y datos sin separar canales, terminas obligando al usuario a hacer scraping de texto frágil.

Un ejemplo simple: si tu comando deploy imprime en stdout el resultado final y en stderr los warnings, un script puede capturar el estado sin ruido. Si en cambio mezclas todo en una sola salida, el usuario tendrá que filtrar líneas a mano. Parece un detalle pequeño, pero en equipos con pipelines reales ese detalle se convierte en horas perdidas.

También cambia la forma en que documentas. No basta con listar flags. Tienes que explicar el flujo esperado, los defaults y los casos borde. Una CLI moderna no se aprende por intuición; se aprende porque sus decisiones son coherentes.

Los principios que más importan según clig.dev

Las Command Line Interface Guidelines ponen el foco en principios que parecen obvios, pero rara vez se aplican bien. El primero es la claridad: el nombre del comando debe decir qué hace y las opciones deben seguir una lógica consistente. El segundo es la predictibilidad: si algo funciona de una manera hoy, no debería cambiar sin una razón fuerte y una transición clara.

Otro punto clave es el manejo de errores. Un buen error no solo dice que algo falló. Dice qué falló, por qué pudo fallar y qué puedes hacer después. Si un comando requiere autenticación, por ejemplo, no sirve de mucho decir “unauthenticated”. Es mejor indicar si falta iniciar sesión, si el token expiró o si no tienes permisos para ese recurso.

La guía también insiste en separar la interfaz humana del formato para máquinas. Eso es muy útil cuando tu CLI se usa en scripts, CI o por agentes. Una salida bonita puede ser útil para personas, pero un formato estable y documentado es lo que permite automatización confiable.

Claves de diseño que sí te ahorran soporte

Hay decisiones que parecen menores y terminan siendo las más caras si las haces mal:

1. Nombres consistentes para comandos y subcomandos.
2. Flags con significado estable, sin reusar -f para tres cosas distintas.
3. Salidas que distinguen entre datos, warnings y errores.
4. Códigos de salida documentados.
5. Ayuda integrada que responda rápido y con ejemplos reales.

Si tu CLI tiene más de 10 comandos, estas reglas dejan de ser teoría. Empiezas a notar que los usuarios repiten patrones, y si el diseño no los acompaña, cada nueva opción aumenta la fricción.

La documentación oficial de clig.dev insiste en que la CLI debe ser una interfaz de producto, no solo una capa técnica. Si quieres revisar el enfoque base, la referencia está en https://clig.dev/. Si te interesa la convención de flags y argumentos en el ecosistema Unix, también vale revisar la documentación de getopt y herramientas similares en la documentación de tu sistema o lenguaje.

Errores, salida y códigos: donde se rompe la confianza

Muchísimas CLIs fallan en el mismo punto: cuando algo sale mal. El usuario ejecuta un comando con parámetros correctos, pero el error que recibe es genérico, largo o inútil. En una herramienta moderna, el error tiene que ser accionable. Si no, obligas a la persona a probar combinaciones al azar.

Un patrón sano es este: stdout para resultados, stderr para diagnósticos, y códigos de salida documentados. No necesitas inventar una taxonomía enorme. Con unos pocos códigos consistentes ya mejoras mucho la experiencia. Por ejemplo, 0 para éxito, 1 para error general y códigos diferenciados para validación, permisos o ausencia de recurso, si tu herramienta lo amerita.

También conviene pensar en el formato del error. Un texto como “invalid input” no ayuda demasiado. En cambio, “No pudimos leer config.yml: falta el campo projectId” ya apunta al problema real. Si además agregas una sugerencia de corrección, mejor.

Un patrón útil para mensajes de error

Puedes pensar cada error en tres capas:

• Qué pasó.
• Dónde pasó.
• Qué hacer ahora.

Ejemplo:

Error: no se pudo autenticar con el servidor.
Causa: el token de acceso expiró hace 2 horas.
Siguiente paso: ejecuta `tool login` o renueva la variable `TOOL_TOKEN`.

Ese formato no es bonito por sí mismo. Es útil porque reduce ida y vuelta. Para una persona técnica, eso vale más que un mensaje elegante pero vago.

En CLIs que generan archivos o tocan infraestructura, también conviene aclarar si una operación fue parcial. Si un comando falla después de crear 3 de 5 recursos, decirlo explícitamente evita confusión. La salida debe ayudar a decidir si reintentas, corriges o limpias estado.

Diseñar para agentes y automatización sin romper a las personas

Las herramientas de terminal ya no las usan solo humanos. También las consumen agentes, runners y sistemas que interpretan instrucciones para ejecutar tareas. Eso hace que la consistencia sea todavía más importante. Un agente no “adivina” tu intención: sigue patrones. Si cambias el formato de salida cada semana, lo obligas a fallar o a depender de heurísticas frágiles.

Aquí entran varias prácticas que las guías modernas empujan con razón. Una es ofrecer una salida estructurada, idealmente JSON, cuando la tarea lo necesite. Otra es separar claramente comandos interactivos de comandos no interactivos. También ayuda que los prompts o confirmaciones tengan una forma predecible, porque los agentes suelen necesitar saber cuándo una acción requiere aprobación humana.

Si trabajas en productos usados por equipos de desarrollo en LatAm, esto también importa por conectividad y latencia. Una CLI que hace preguntas innecesarias o manda demasiados pasos al usuario complica flujos remotos, sesiones SSH y automatizaciones en CI. Menos fricción significa menos errores en entornos donde el tiempo de respuesta ya es variable.

Señales de que tu CLI no está lista para automatización

Revisa si tu herramienta hace alguna de estas cosas:

• Imprime banners grandes antes del resultado.
• Mezcla logs con datos en la misma salida.
• Cambia el orden de campos entre versiones.
• Pide confirmación aunque el comando ya recibió --yes.
• Devuelve errores distintos para el mismo problema según el contexto.

Si marcaste dos o más, tienes trabajo pendiente. No hace falta rehacer todo. A veces basta con agregar un modo silencioso, un modo JSON y una salida de ayuda más clara.

Un detalle importante: la automatización no elimina la experiencia humana. La mejora. Si tu CLI es fácil de scriptar, también suele ser más fácil de usar a mano porque sus reglas son más claras.

Accesibilidad, lenguaje y consistencia visual en terminal

La accesibilidad en una CLI no se limita a colores. También incluye lenguaje, ritmo de salida y compatibilidad con lectores de pantalla o terminales con capacidades limitadas. Si dependes solo del color para transmitir estado, dejas afuera a personas con daltonismo o con terminales sin soporte completo.

Las guías modernas recomiendan usar color con moderación y nunca como único canal de información. También conviene evitar animaciones innecesarias o barras de progreso que ensucien logs. En terminales remotas, esas animaciones pueden ser más molestas que útiles.

Otro punto práctico es el lenguaje. En vez de mensajes largos o técnicos sin contexto, usa frases cortas, verbos claros y una estructura que la persona pueda escanear rápido. Una CLI no necesita sonar sofisticada. Necesita ser entendible en menos de 5 segundos.

Cómo escribir ayuda que sí se usa

La pantalla de --help suele ser el primer contacto real con tu herramienta. Si ahí fallas, el resto importa menos. Una ayuda útil debería incluir:

1. Qué hace el comando.
2. 2 o 3 ejemplos reales.
3. Flags obligatorios y opcionales.
4. Valores por defecto.
5. Un camino claro para obtener más detalle.

Ejemplo de estructura razonable:

tool deploy --env production --region us-east-1

tool deploy --help

No necesitas escribir un manual completo en --help. Pero sí evitar el típico bloque de opciones sin contexto. Si un usuario ve --force, debería entender qué fuerza exactamente y qué riesgo implica.

La consistencia visual también cuenta. Si usas indentación, alineación y formato de listas de manera estable, la lectura mejora bastante. Eso ayuda tanto a personas que usan la CLI todos los días como a quienes la abren una vez al mes.

Cómo aplicar estas guías en tu propio proyecto

No hace falta rediseñar toda tu herramienta de una sola vez. Puedes empezar por los puntos que más impacto tienen en soporte y adopción. En la práctica, suele funcionar mejor un plan incremental que una refactorización gigante.

Un orden razonable sería este:

1. Audita la ayuda y los mensajes de error.
2. Separa stdout de stderr correctamente.
3. Define códigos de salida consistentes.
4. Agrega una salida estructurada, si tu CLI produce datos.
5. Revisa nombres de comandos y flags para que sigan una lógica uniforme.

Si tu equipo trabaja con Node.js, Python, Go o Rust, puedes aplicar estos principios sin importar el lenguaje. La implementación cambia, pero el criterio no. En Node, por ejemplo, puedes usar process.stdout y process.stderr de forma explícita. En Go, puedes controlar os.Stdout y os.Stderr. Lo importante es no dejar que todo termine mezclado por comodidad.

También ayuda revisar tu CLI con usuarios reales. No hace falta una investigación enorme. Con 3 o 5 personas que la usen de verdad ya detectas problemas repetidos: nombres confusos, defaults raros, pasos de más o errores poco claros. En herramientas internas, eso suele ser suficiente para encontrar el 80 por ciento de la fricción.

Checklist rápido antes de publicar una versión

• ¿El comando principal se entiende sin leer toda la doc?
• ¿Los errores explican causa y siguiente paso?
• ¿La salida para scripts es estable?
• ¿--help muestra ejemplos reales?
• ¿Los flags son consistentes entre comandos?
• ¿El cambio rompe automatizaciones existentes?

Si la respuesta a dos de esas preguntas es “no”, conviene ajustar antes del release. Una CLI se gana la confianza con repetición, no con promesas.

Tabla resumen

Las Command Line Interface Guidelines no te obligan a escribir una CLI perfecta, pero sí te dan un marco útil para evitar errores muy caros. Si tu producto depende de terminales, automatización o agentes, diseñar bien la interfaz ya no es un detalle técnico. Es parte del producto.