Buenas Prácticas para CLI
Reglas para CLIs que son descubribles, automatizables y respetuosas con el tiempo del usuario.
Cómo Usar Esta Lista
- Aplica al diseñar nuevos comandos o al revisar PRs de CLI.
- Cada regla apoya la usabilidad humana o la automatización de scripts.
- Añade ejemplos de
--helppara cada subcomando.
A - Diseño de Interfaz
- Propósito único y claro. Una herramienta, un trabajo. Divide funciones no relacionadas.
- Subcomandos para verbos.
mi_app deploy, nomi_app --deploy. - Nombres de flags consistentes.
--verbose/-ven todos los subcomandos. - Texto de ayuda significativo. Cada argumento documentado con un ejemplo.
B - Automatización (Scriptability)
- Códigos de salida significativos. 0 para éxito, códigos distintos para fallos distintos.
- stdout para datos, stderr para logs. La salida se puede canalizar (pipe).
- Flag
--jsono--plain. Opción de salida legible por máquina. - Modo no interactivo.
--yes/--no-inputpara CI y scripts.
C - Configuración
- Flags anulan variables de entorno, que anulan archivo de configuración. Documenta la precedencia.
- Secretos solo a través de variables de entorno. Nunca en archivos de configuración en git.
- Valores predeterminados sensatos. El caso común funciona sin flags.
- Validar pronto. Fallar rápidamente ante configuración incorrecta antes de que comience el trabajo.
D - Experiencia de Usuario
- Progreso para operaciones largas. Spinner o barra de progreso (Rich/tqdm).
- Confirmar acciones destructivas. Predeterminado No en eliminar/remover.
- Mensajes de error accionables. Qué falló, por qué y cómo solucionarlo.
- Autocompletado de shell. Autocompletado de Click/Typer instalado y documentado.
E - Distribución
- Punto de entrada en pyproject.toml. Nombre de comando instalable.
- Compatible con pipx. Instalación aislada con dependencias mínimas.
- Semver para cambios en CLI. Cambios de flags que rompen incrementan MAJOR.
- README con inicio rápido. Instalación, primer comando, ejemplos comunes.
Preguntas Frecuentes
¿Cuántos subcomandos?
Tantos como sean necesarios, pero cada uno debe ser descubrible a través de --help.
¿Las CLIs deben ser interactivas por defecto?
No. Interactivas solo cuando se solicitan explícitamente o no se proporcionan argumentos para un asistente.
¿argparse o Click?
argparse para lo simple/sin dependencias. Click/Typer para herramientas de producción multi-comando.
¿Cómo se deprecia un flag?
Advertencia al usarlo, documentar en la ayuda, eliminar en la próxima versión mayor.
¿Flag de nivel de logging?
-v una vez = INFO, dos veces = DEBUG. Registrar en stderr.
¿Cómo manejo las contraseñas?
Variable de entorno o solicitar con entrada oculta. Nunca flags de argv.
¿Estrategia de pruebas de CLI?
CliRunner/typer para pruebas de integración. Probar la lógica central por separado.
¿Flag de versión?
--version en cada herramienta. Consistente en tu suite de CLI.
¿Salida a color?
Automática por defecto. Soporte para --no-color y NO_COLOR=1.
¿Cuánto debe ser --help?
Conciso por flag. Enlaza a la documentación para ejemplos largos.
Relacionados
- Conceptos Básicos de CLI - fundamentos
- argparse - análisis de librería estándar
- Empaquetado y Distribución de CLIs - distribución
- Configuración y Entorno - configuración
Versiones de Stack: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.