Noções Básicas de CLI

10 exemplos para você começar com Ferramentas de CLI - 7 básicos e 3 intermediários.

Pré-requisitos

• Python 3.14.0
• Opcional: uv add click typer rich para exemplos intermediários

Exemplos Básicos

1. Noções Básicas de sys.argv

A CLI mais simples lê argumentos de sys.argv.

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

• sys.argv[0] é o nome do script
• Código de saída 1 sinaliza erro para scripts shell
• Nenhuma dependência necessária
• Insuficiente para ferramentas reais - use argparse

Relacionado: argparse - análise adequada de argumentos

2. Essenciais do argparse

Análise de argumentos da biblioteca padrão com ajuda gerada automaticamente.

import argparse
 
parser = argparse.ArgumentParser(description="Cumprimenta usuários")
parser.add_argument("name", help="Nome para cumprimentar")
parser.add_argument("--loud", action="store_true", help="Saída em maiúsculas")
args = parser.parse_args()
 
msg = f"Olá, {args.name}!"
print(msg.upper() if args.loud else msg)

• --help gerado automaticamente
• action="store_true" para flags booleanas
• Argumentos posicionais e opcionais suportados
• Biblioteca padrão - nenhuma instalação necessária

Relacionado: argparse - guia completo

3. Códigos de Saída

Retorne códigos de saída significativos para integração com shell.

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

• 0 = sucesso, não zero = falha
• Use stderr para mensagens de erro
• Documente os códigos de saída em --help
• CI e scripts shell verificam $?

4. stdin/stdout/stderr

CLIs leem de stdin e escrevem para stdout; erros vão para stderr.

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

• stdout para saída de dados (canalizável)
• stderr para logs e erros (não canalizados)
• Permite composição: cmd1 | cmd2
• Logs --verbose devem ir para stderr

5. Subcomandos

Organize a CLI em verbos: git commit, docker run.

import argparse
 
parser = argparse.ArgumentParser()
sub = parser.add_subparsers(dest="command", required=True)
 
add = sub.add_parser("add", help="Adicionar item")
add.add_argument("name")
 
remove = sub.add_parser("remove", help="Remover item")
remove.add_argument("id", type=int)
 
args = parser.parse_args()

• add_subparsers cria grupos de comandos
• Cada subparser tem seus próprios argumentos
• dest="command" identifica qual subcomando foi executado
• Base para ferramentas multi-comando

Relacionado: Click - subcomandos baseados em decoradores

6. Conversão de Tipo

argparse converte argumentos de string para valores tipados.

parser.add_argument("--port", type=int, default=8000)
parser.add_argument("--ratio", type=float, default=0.5)
parser.add_argument("--tags", nargs="+")  # uma ou mais strings

• type=int valida e converte
• nargs="+" coleta múltiplos valores
• choices=[...] restringe valores válidos
• Tipos inválidos produzem mensagens de erro claras

7. Variáveis de Ambiente

Leia a configuração de variáveis de ambiente como fallback.

import os
 
api_key = os.environ.get("API_KEY")
if not api_key:
    raise SystemExit("Defina a variável de ambiente API_KEY")

• Aplicativos 12-factor usam variáveis de ambiente para configuração
• A flag substitui a variável de ambiente é a precedência comum
• Nunca imprima segredos para stdout
• Documente as variáveis de ambiente necessárias em --help

Relacionado: Configuração e Ambiente - camadas de configuração

Exemplos Intermediários

8. Click para Ergonomia

Click usa decoradores para um código CLI mais limpo.

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

• Decoradores substituem o boilerplate do argparse
• click.echo lida com a codificação corretamente
• @click.group() para subcomandos
• Saída colorida e prompts integrados

Relacionado: Click - guia completo do Click

9. Rich para Saída

Tabelas formatadas, barras de progresso e realce de sintaxe.

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

• Tabelas, painéis e barras de progresso
• Detecção automática da largura do terminal
• Retrocede graciosamente em terminais "burros"
• Use para saída voltada para humanos; texto simples para análise por máquina

Relacionado: Saída Rich - guia de formatação

10. Empacotar e Distribuir

Envie CLI via entry points e pipx.

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

pipx install mytool
mytool --help

• [project.scripts] registra o comando na instalação
• pipx isola a CLI em seu próprio venv
• Os usuários obtêm um comando global sem poluir o Python do sistema
• Veja a seção de empacotamento para o fluxo de trabalho completo

Relacionado: Empacotamento e Distribuição de CLIs

Versões da Stack: Esta página foi 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+ e uv 0.6+.