Mejores prácticas para CLIs modernas

Cuando una CLI está bien pensada, casi desaparece. Tú escribes un comando, recibes una respuesta clara y sigues con tu trabajo. Cuando está mal diseñada, pasa lo contrario: flags inconsistentes, mensajes ambiguos, errores que no ayudan y una experiencia que obliga a leer código fuente o abrir issues para entender qué hace la herramienta.

Las Command Line Interface Guidelines de clig.dev siguen siendo una referencia muy útil porque no se quedan en la estética de la terminal. Hablan de comportamiento, consistencia, automatización, accesibilidad y de algo que muchos equipos olvidan: una CLI también es un producto. Si la usas para scripts, CI/CD o tareas repetitivas, cualquier detalle raro se multiplica.

Por qué las guías de CLI siguen vigentes

La terminal no es un museo. Sigue siendo parte central del trabajo diario de desarrollo, operaciones y automatización. Herramientas como Git, npm, pnpm, Docker, Terraform o gh demuestran que una CLI puede ser potente sin volverse hostil. Las guías de clig.dev ayudan justamente a eso: a reducir fricción en tareas frecuentes.

La razón principal es simple. Una buena CLI no solo debe funcionar, también debe ser predecible. Si un comando acepta --help en un proyecto y en otro usa help, si un error sale por stdout en vez de stderr, o si un subcomando cambia de nombre sin aviso, tú terminas perdiendo tiempo en algo que debería ser mecánico. La documentación oficial de clig.dev insiste en patrones consistentes y en mensajes claros, y eso sigue siendo válido aunque tu herramienta use TypeScript, Go, Rust o Python.

Además, hoy una CLI rara vez vive sola. Se conecta con scripts, GitHub Actions, Docker Compose, wrappers internos y pipelines de despliegue. Por eso importa que la salida sea estable y fácil de parsear. Si cambias el formato de una línea, puedes romper automatizaciones en producción. Esa es una razón práctica, no teórica, para seguir estas guías.

Lo que cambia cuando una CLI es tratada como producto

Cuando diseñas una CLI como producto, dejas de pensar solo en el comando feliz y empiezas a pensar en casos reales. Qué pasa si el usuario escribe mal un flag. Qué pasa si falta una variable de entorno. Qué pasa si el comando tarda 40 segundos. Qué pasa si se ejecuta dentro de un contenedor sin TTY.

Ese cambio mental se nota en detalles concretos. Por ejemplo, una herramienta que imprime progreso visual solo si detecta terminal interactiva evita ensuciar logs. Otra que ofrece --json permite integrar el resultado en scripts sin hacer parsing de texto libre. Y una que documenta cada subcomando en --help reduce el soporte manual.

También cambia la relación con el usuario. En vez de obligarte a adivinar, la CLI te guía. En vez de esconder errores, te dice qué pasó y cómo corregirlo. Eso no es un lujo, es parte de la usabilidad mínima.

Principios que más impacto tienen en el uso diario

De todas las recomendaciones, hay varias que tienen impacto inmediato. La primera es consistencia. Si usas --verbose en un comando, no inventes -v para otro sin una razón fuerte. Si un flag espera una ruta, no la cambies a nombre de recurso en otro subcomando. El cerebro humano agradece la repetición cuando trabaja con herramientas de texto.

La segunda es claridad en la salida. Los mensajes de error deben decir qué falló, por qué falló y qué puedes hacer. No basta con un “invalid input”. Mejor algo como “No se encontró config.yaml en el directorio actual. Crea el archivo o usa --config <ruta>”. Si además muestras el código de salida correcto, el script que consume tu CLI puede reaccionar de forma confiable.

La tercera es compatibilidad con automatización. Una CLI moderna no debería asumir que siempre habrá una persona mirando la pantalla. A veces la corre un job nocturno, un container efímero o un runner en GitHub Actions. Por eso conviene separar salida humana y salida pensada para máquinas.

Entrada, salida y errores deben tener reglas claras

Una regla práctica es esta: stdout para resultados, stderr para errores y logs de diagnóstico. Parece básico, pero muchas herramientas lo rompen. Si mezclas todo, luego no puedes redirigir la salida de forma limpia.

También conviene definir formatos estables. Si ofreces texto legible, mantenlo simple. Si ofreces JSON, documenta el esquema y evita cambios silenciosos. Si agregas colores, asegúrate de desactivarlos cuando la salida no sea interactiva. La documentación oficial de clig.dev y muchas guías de Unix coinciden en este punto.

Un ejemplo útil es separar comandos que están pensados para personas de comandos que están pensados para scripts. A veces basta con un flag --json o --quiet. En otras herramientas, conviene tener un subcomando específico como tool status --json. Lo importante es que tú no obligues a parsear texto diseñado para humanos.

Tabla de decisiones prácticas

Diseño de comandos que no obliga a memorizar

Una buena CLI se puede descubrir sin leer un manual de 30 páginas. Eso no significa esconder complejidad, sino organizarla. Los comandos principales deben ser obvios, y los subcomandos deben seguir una lógica predecible. Si tu herramienta gestiona proyectos, probablemente create, list, status y delete sean más claros que nombres creativos pero opacos.

La documentación oficial de clig.dev recomienda pensar en verbos, objetos y flujos. Esa idea sigue funcionando porque coincide con cómo la gente razona en la terminal. Tú no quieres memorizar una gramática rara, quieres ejecutar tareas. Si el comando refleja la tarea, la herramienta se aprende más rápido.

También ayuda mucho que --help sea realmente útil. No basta con listar flags. Debe mostrar ejemplos, valores por defecto y diferencias entre opciones similares. Si un flag acepta una ruta relativa, dilo. Si otro espera una lista separada por comas, dilo también. El costo de escribir esa precisión una vez es menor que el costo de responder la misma duda cien veces.

Ejemplos concretos de ayuda útil

Un --help bien hecho puede verse así:

Usage: acme deploy [options]

Options:
  --env <name>       Environment name: dev, staging, prod
  --config <path>    Path to config file, default: ./acme.json
  --json             Print machine-readable output
  --dry-run          Show actions without making changes

Ese formato no es decorativo. Te dice qué hace el comando, qué espera y qué puedes automatizar. Si además agregas ejemplos reales, reduces el tiempo de descubrimiento. Por ejemplo:

acme deploy --env staging --dry-run
acme deploy --env prod --config ./configs/prod.json --json

En equipos grandes, este tipo de ayuda ahorra tiempo de onboarding. Un desarrollador nuevo puede entender la herramienta sin abrir un ticket ni buscar en chats viejos. Eso, en la práctica, también es productividad.

Automatización, scripts y CI: donde se nota la calidad

Muchas CLIs parecen buenas hasta que las metes en CI. Ahí aparecen los problemas reales: prompts interactivos que bloquean el pipeline, colores que ensucian logs, salidas no deterministas y errores que no cortan el proceso con el código correcto. Si tu herramienta va a vivir en automatización, debes probarla en ese entorno desde el inicio.

Una recomendación útil es detectar si hay TTY y adaptar la salida. Si hay terminal interactiva, puedes mostrar progreso, colores y confirmaciones. Si no la hay, mejor reducir ruido. Esto no solo mejora la experiencia, también evita que un log de 2,000 líneas se vuelva ilegible.

Otra práctica importante es hacer que los comandos sean idempotentes cuando tenga sentido. Si deploy se ejecuta dos veces con la misma configuración, el resultado no debería ser impredecible. Si init crea archivos, debería avisar claramente si ya existen. Si delete borra recursos, conviene pedir confirmación o usar --force con mucho cuidado.

Qué revisar antes de publicar una CLI

1. Ejecuta el comando en una terminal interactiva y en un job de CI.
2. Verifica que los errores salgan por stderr y que el exit code cambie según el fallo.
3. Prueba --help, --version, --json y --quiet si los ofreces.
4. Confirma que los mensajes no dependan de colores para ser entendidos.
5. Revisa que los ejemplos de la documentación funcionen tal cual están escritos.
6. Haz una prueba con entrada inválida: archivo faltante, flag mal escrito y valor fuera de rango.

Si tu CLI produce datos para otros sistemas, documenta el formato con precisión. Un JSON estable es más valioso que una frase bonita. Para casos donde necesites una referencia de salida estructurada, puedes apoyarte en la documentación oficial de tu lenguaje o framework, pero la regla es la misma: no cambies el contrato sin versionar.

Un ejemplo simple de salida estructurada sería este:

{
  "status": "ok",
  "environment": "staging",
  "deployed": 3,
  "duration_ms": 1842
}

Con algo así, un script puede leer campos concretos sin depender de texto libre. Eso es especialmente útil en equipos que trabajan con despliegues, migraciones o reportes automatizados.

Accesibilidad, errores y detalles que sí importan

La accesibilidad también existe en la terminal. No toda persona usa el mismo terminal, el mismo tema o el mismo ritmo de lectura. Por eso conviene no depender solo del color para comunicar estado. Si algo falla, añade texto explícito como “ERROR”, “WARN” o “OK”. Si usas color, que sea un refuerzo, no la única señal.

Los mensajes de error merecen atención de verdad. Un error útil no culpa al usuario ni lo deja con una pista vaga. Debe decir qué pasó, dónde pasó y qué hacer después. Por ejemplo, en vez de “permission denied”, puedes decir “No tienes permisos para escribir en /var/lib/acme. Ejecuta el comando con un usuario con permisos o cambia la ruta con --output”.

También conviene pensar en localización y contexto regional. En Latinoamérica, muchas personas trabajan con equipos heterogéneos, conexiones inestables y entornos donde el soporte no está en la misma zona horaria. Una CLI que explica bien sus errores reduce dependencia de soporte remoto. Si además documentas rutas, variables de entorno y ejemplos con nombres claros, ayudas a equipos de la región a adoptar la herramienta más rápido.

Mensajes que ayudan de verdad

Un buen mensaje de error suele incluir tres piezas:

• Qué ocurrió.
• Qué valor o archivo causó el problema.
• Cómo resolverlo o qué opción usar.

Por ejemplo:

Error: no se encontró el archivo ./deploy.yaml
Sugerencia: crea el archivo o ejecuta `acme deploy --config ./ruta/alternativa.yaml`

Ese formato es corto, pero suficiente. No te pide adivinar. No te obliga a revisar código ni a buscar en una issue cerrada hace dos años.

Si tu CLI tiene validación de argumentos, devuélvela lo antes posible. El usuario no debería esperar 20 segundos para descubrir que un flag está mal escrito. Validar temprano ahorra tiempo y reduce frustración.

Qué tomar hoy de clig.dev y cómo aplicarlo mañana

No necesitas rehacer toda tu herramienta para beneficiarte de estas guías. Puedes empezar con cambios pequeños y medibles. Primero, revisa si tu CLI tiene una salida consistente. Luego, valida si --help responde preguntas reales. Después, prueba tus comandos en CI y en un entorno sin interacción. Con eso ya cubres una parte importante del valor de clig.dev.

Si estás diseñando una herramienta nueva, define desde el inicio reglas simples: nombres predecibles, errores útiles, salida separada para humanos y máquinas, y ejemplos reales en la documentación. Si ya tienes una CLI en producción, haz una auditoría de experiencia. Busca flags duplicados, mensajes ambiguos y comandos que rompen scripts. Muchas veces no hace falta reescribir, solo ordenar.

La mejor señal de que vas bien es esta: cuando alguien nuevo puede usar la herramienta sin pedir ayuda para cada paso. Si además tu CLI funciona en automatización sin parches raros, entonces ya estás diseñando algo que escala mejor. No por moda, sino porque respeta el tiempo de quien la usa.

Tabla resumen