Boas Práticas de CLI
Regras para CLIs que são descobertas, scriptáveis e respeitam o tempo do usuário.
Como Usar Esta Lista
- Aplique ao projetar novos comandos ou revisar PRs de CLI
- Cada regra suporta usabilidade humana ou automação de script
- Adicione exemplos de
--helppara cada subcomando
A - Design da Interface
- Propósito único e claro. Uma ferramenta, um trabalho. Divida funções não relacionadas.
- Subcomandos para verbos.
meuapp deploy, nãomeuapp --deploy. - Nomes de flags consistentes.
--verbose/-vem todos os subcomandos. - Texto de ajuda significativo. Cada argumento documentado com exemplo.
B - Scriptabilidade
- Códigos de saída significativos. 0 sucesso, códigos distintos para falhas distintas.
- stdout para dados, stderr para logs. Saída que pode ser canalizada (pipeable).
- Flag --json ou --plain. Opção de saída legível por máquina.
- Modo não interativo.
--yes/--no-inputpara CI e scripts.
C - Configuração
- Flags substituem variáveis de ambiente que substituem arquivo de configuração. Documente a precedência.
- Segredos apenas via ambiente. Nunca em arquivos de configuração no git.
- Padrões sensatos. O caso comum funciona sem flags.
- Valide cedo. Falhe rapidamente em configurações incorretas antes do trabalho começar.
D - Experiência do Usuário
- Progresso para operações longas. Spinner ou barra de progresso (Rich/tqdm).
- Confirme ações destrutivas. Padrão Não em delete/remove.
- Mensagens de erro acionáveis. O que falhou, por quê e como corrigir.
- Autocompletar do shell. Autocompletar Click/Typer instalado e documentado.
E - Distribuição
- Ponto de entrada em pyproject.toml. Nome do comando instalável.
- Compatível com pipx. Instalação isolada com dependências mínimas.
- Semver para mudanças de CLI. Mudanças de flags que quebram a compatibilidade incrementam MAJOR.
- README com quickstart. Instalação, primeiro comando, exemplos comuns.
FAQs
Quantos subcomandos?
Quantos forem necessários, mas cada um deve ser descoberto via --help.
CLIs devem ser interativas por padrão?
Não. Interativo apenas quando explicitamente solicitado ou quando nenhum argumento é fornecido para um assistente.
argparse ou Click?
argparse para ferramentas simples/sem dependências. Click/Typer para ferramentas de produção com múltiplos comandos.
Como posso descontinuar uma flag?
Aviso ao usar, documente na ajuda, remova na próxima versão principal.
Flag de nível de log?
-v uma vez = INFO, duas vezes = DEBUG. Log para stderr.
Como lidar com senhas?
Variável de ambiente ou prompt com entrada oculta. Nunca flags de argv.
Estratégia de teste de CLI?
CliRunner/typer para testes de integração. Teste a lógica principal separadamente.
Flag de versão?
--version em toda ferramenta. Consistente em toda a sua suíte de CLI.
Saída colorida?
Padrão automático. Suporte a --no-color e NO_COLOR=1.
Qual o tamanho ideal para --help?
Conciso por flag. Link para a documentação para exemplos longos.
Relacionados
- Fundamentos de CLI - fundamentos
- argparse - análise do stdlib
- Empacotamento e Distribuição de CLIs - distribuição
- Configuração e Ambiente - configuração
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+.