Conceptos básicos de la CLI

10 ejemplos para empezar con herramientas de línea de comandos (CLI): 7 básicos y 3 intermedios.

Prerrequisitos

• Python 3.14.0
• Opcional: uv add click typer rich para los ejemplos intermedios

Ejemplos básicos

1. Conceptos básicos de sys.argv

La CLI más simple lee argumentos de sys.argv.

import sys
 
if len(sys.argv) < 2:
    print("Uso: greet.py NOMBRE")
    sys.exit(1)
print(f"¡Hola, {sys.argv[1]}!")

• sys.argv[0] es el nombre del script
• El código de salida 1 señala un error a los scripts de shell
• No se necesitan dependencias
• Insuficiente para herramientas reales: usa argparse

Relacionado: argparse - análisis adecuado de argumentos

2. Esenciales de argparse

Análisis de argumentos de la biblioteca estándar con ayuda generada automáticamente.

import argparse
 
parser = argparse.ArgumentParser(description="Saluda a los usuarios")
parser.add_argument("name", help="Nombre a saludar")
parser.add_argument("--loud", action="store_true", help="Salida en mayúsculas")
args = parser.parse_args()
 
msg = f"¡Hola, {args.name}!"
print(msg.upper() if args.loud else msg)

• --help generado automáticamente
• action="store_true" para indicadores booleanos
• Admite argumentos posicionales y opcionales
• Biblioteca estándar: no se necesita instalación

Relacionado: argparse - guía completa

3. Códigos de salida

Devuelve códigos de salida significativos para la integración con el shell.

import sys
 
def main() -> int:
    try:
        run()
        return 0
    except FileNotFoundError:
        print("Archivo no encontrado", file=sys.stderr)
        return 2
    except PermissionError:
        return 13
 
sys.exit(main())

• 0 = éxito, distinto de cero = fallo
• Usa stderr para mensajes de error
• Documenta los códigos de salida en --help
• CI y scripts de shell comprueban $?

4. stdin/stdout/stderr

Las CLIs leen de stdin y escriben en stdout; los errores van a stderr.

import sys
 
for line in sys.stdin:
    print(line.strip().upper())
 
# Uso: cat file.txt | python upper.py > out.txt

• stdout para salida de datos (enlazable)
• stderr para registros y errores (no enlazados)
• Permite la composición: cmd1 | cmd2
• Los registros --verbose deben ir a stderr

5. Subcomandos

Organiza la CLI en verbos: git commit, docker run.

import argparse
 
parser = argparse.ArgumentParser()
sub = parser.add_subparsers(dest="command", required=True)
 
add = sub.add_parser("add", help="Añadir elemento")
add.add_argument("name")
 
remove = sub.add_parser("remove", help="Eliminar elemento")
remove.add_argument("id", type=int)
 
args = parser.parse_args()

• add_subparsers crea grupos de comandos
• Cada subparser tiene sus propios argumentos
• dest="command" identifica qué subcomando se ejecutó
• Base para herramientas de múltiples comandos

Relacionado: Click - subcomandos basados en decoradores

6. Conversión de tipos

argparse convierte los argumentos de cadena en valores tipados.

parser.add_argument("--port", type=int, default=8000)
parser.add_argument("--ratio", type=float, default=0.5)
parser.add_argument("--tags", nargs="+")  # una o más cadenas

• type=int valida y convierte
• nargs="+" recopila múltiples valores
• choices=[...] restringe los valores válidos
• Los tipos no válidos producen mensajes de error claros

7. Variables de entorno

Lee la configuración de las variables de entorno como respaldo.

import os
 
api_key = os.environ.get("API_KEY")
if not api_key:
    raise SystemExit("Establece la variable de entorno API_KEY")

• Las aplicaciones 12-factor usan variables de entorno para la configuración
• El indicador anula la variable de entorno es la precedencia común
• Nunca imprimas secretos en stdout
• Documenta las variables de entorno requeridas en --help

Relacionado: Configuración y Entorno - capas de configuración

Ejemplos intermedios

8. Click para ergonomía

Click usa decoradores para un código CLI más limpio.

import click
 
@click.command()
@click.option("--count", default=1, help="Número de saludos")
@click.argument("name")
def greet(name, count):
    for _ in range(count):
        click.echo(f"¡Hola, {name}!")
 
if __name__ == "__main__":
    greet()

• Los decoradores reemplazan el código repetitivo de argparse
• click.echo maneja la codificación correctamente
• @click.group() para subcomandos
• Salida en color y prompts integrados

Relacionado: Click - guía completa de Click

9. Rich para salida

Tablas formateadas, barras de progreso y resaltado de sintaxis.

from rich.console import Console
from rich.table import Table
 
console = Console()
table = Table(title="Usuarios")
table.add_column("ID", style="cyan")
table.add_column("Email")
table.add_row("1", "ada@example.com")
console.print(table)

• Tablas, paneles y barras de progreso
• Detección automática del ancho de terminal
• Retrocede con gracia en terminales "tontas"
• Úsalo para salida orientada a humanos; texto plano para análisis por máquinas

Relacionado: Salida Rich - guía de formato

10. Empaquetar y distribuir

Envía la CLI a través de puntos de entrada y pipx.

[project.scripts]
mytool = "mytool.cli:main"

pipx install mytool
mytool --help

• [project.scripts] registra el comando al instalar
• pipx aísla la CLI en su propio entorno virtual
• Los usuarios obtienen un comando global sin contaminar el Python del sistema
• Consulta la sección de empaquetado para el flujo de trabajo completo

Relacionado: Empaquetado y distribución de CLIs

Versiones de la pila: Esta página se escribió 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+.