Criando CLI em Python com argparse

Uma interface de linha de comando (CLI) permite que usuários executem tarefas digitando comandos em um terminal. Em Python, a biblioteca padrão docs.python.org oferece o módulo argparse, que simplifica a criação de CLIs robustas e amigáveis. Neste artigo você aprenderá, passo a passo, a montar sua própria ferramenta de linha de comando usando argparse, desde a estrutura inicial até a distribuição final.

O que é uma CLI e por que usar argparse

Uma CLI é um programa que aceita argumentos e opções diretamente da linha de comando. Ela é útil para automatizar tarefas, integrar scripts a pipelines ou criar utilitários leves. O módulo argparse gera automaticamente mensagens de ajuda, valida tipos de dados e trata erros de entrada, reduzindo a quantidade de código que você precisa escrever. Segundo a documentação oficial, argparse “torna fácil a escrita de interfaces de linha de comando amigáveis”

Instalando e preparando o ambiente

Antes de começar, verifique se o Python está instalado (versão 3.6 ou superior). Crie um ambiente virtual para isolar as dependências:

1. Abra o terminal.
2. Execute python -m venv venv.
3. Ative o ambiente: source venv/bin/activate (Linux/macOS) ou venv\Scripts\activate (Windows).
4. Instale pacotes adicionais, se precisar, com pip install -r requirements.txt.

O argparse já vem incluído, então nenhuma instalação extra é necessária.

Estrutura básica de um programa com argparse

Um script mínimo tem três partes: importação, definição do parser e execução da lógica.

Exemplo simples (salve como exemplo.py):

import argparse

parser = argparse.ArgumentParser(description='Exemplo de CLI com argparse')
parser.add_argument('nome', help='Nome da pessoa')
parser.add_argument('-a', '--idade', type=int, help='Idade da pessoa')
args = parser.parse_args()

print(f'Olá, {args.nome}! Você tem {args.idade or "idade desconhecida"} anos.')

Quando executado, o programa aceita um argumento posicional (nome) e uma opção opcional (--idade).

Argumentos posicionais vs opcionais

Argumentos posicionais são obrigatórios e são identificados pela ordem em que aparecem. Já os opcionais são precedidos por um hífen (-) ou dois hífens (--) e podem ter valores padrão.

Veja mais detalhes sobre argumentos em delftstack.com.

Tipos de ação e valores padrão

O parâmetro action controla como o argumento será tratado. Alguns valores comuns:

• store – salva o valor (padrão).
• store_true – cria um flag que vira True quando presente.
• append – permite múltiplas ocorrências, armazenando-as em uma lista.

Você pode definir um valor padrão com default=. Por exemplo, parser.add_argument('--modo', default='normal') garante que args.modo sempre tenha um valor.

Mensagens de ajuda automáticas

Ao usar ArgumentParser, o -h ou --help gera uma descrição completa:

$ python exemplo.py -h
usage: exemplo.py [-h] [-a IDADE] nome

Exemplo de CLI com argparse

positional arguments:
  nome          Nome da pessoa

optional arguments:
  -h, --help    show this help message and exit
  -a IDADE, --idade IDADE
                Idade da pessoa

Personalize a ajuda com os parâmetros description, epilog e prog. Para boas práticas, inclua exemplos de uso na descrição.

Subcomandos e interfaces mais complexas

Projetos maiores podem precisar de subcomandos, como git commit ou docker run. Use add_subparsers() para criar grupos de argumentos independentes.

Exemplo de subcomandos:

parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers(dest='comando')

# subcomando "add"
add_parser = subparsers.add_parser('add')
add_parser.add_argument('arquivo')

# subcomando "remove"
rm_parser = subparsers.add_parser('remove')
rm_parser.add_argument('arquivo')

Depois, basta verificar args.comando e chamar a função correspondente.

Testando a CLI localmente

Execute o script diretamente no terminal para validar o comportamento. Use --help para conferir a documentação gerada. Para testes automatizados, o módulo unittest pode simular sys.argv:

import sys
from unittest import mock

with mock.patch.object(sys, 'argv', ['prog.py', 'Alice', '--idade', '30']):
    args = parser.parse_args()
    assert args.nome == 'Alice'
    assert args.idade == 30

Essa abordagem garante que mudanças futuras não quebrem a interface.

Distribuindo a ferramenta (setup.py e entry points)

Para que outros usuários instalem sua CLI com pip, crie um setup.py que define um entry point:

from setuptools import setup, find_packages

setup(
    name='minha_cli',
    version='0.1.0',
    packages=find_packages(),
    entry_points={
        'console_scripts': [
            'minha-cli = extension.__main__:main',
        ],
    },
)

Depois, publique no PyPI ou instale localmente com pip install .. O comando minha-cli ficará disponível em qualquer terminal.

Dicas e boas práticas

• Use nomes claros e curtos para opções.
• Forneça exemplos na descrição da ajuda.
• Defina tipos (type=int, type=float) para evitar erros de conversão.
• Evite lógica complexa dentro do bloco de análise; delegue a funções separadas.
• Teste diferentes combinações de argumentos antes de publicar.

Para aprofundar, veja o tutorial oficial de docs.python.org e o artigo prático de medium.com.

FAQ – Perguntas Frequentes

1. O que significa “CLI”?

CLI é a sigla para “Command Line Interface”, ou interface de linha de comando.

2. Preciso instalar argparse?

Não. O módulo já vem incluído nas versões padrão do Python.

3. Como faço um argumento opcional que não recebe valor?

Use action='store_true' para criar um flag que vira True quando usado.

4. Posso usar argparse em scripts que já usam sys.argv?

Sim. argparse lê sys.argv internamente, substituindo a necessidade de parse manual.

5. Como exibir a versão do meu programa?

Adicione parser.add_argument('--version', action='version', version='1.0').

6. O que são subparsers?

São grupos de argumentos que permitem criar subcomandos, como git commit.

7. Posso definir valores padrão diferentes para cada plataforma?

Sim. Use lógica condicional antes de chamar add_argument para ajustar default.

8. Como gerar documentação automática da CLI?

Use a opção --help ou ferramentas como sphinx-argparse para gerar docs.

9. Qual a diferença entre store_const e store_true?

store_const salva um valor fixo definido por const=; store_true salva True quando o flag aparece.

10. Como testar a CLI em CI/CD?

Simule sys.argv com unittest.mock ou execute o script via subprocess.run nos pipelines.

11. Posso usar argparse em projetos que usam click?

É possível, mas geralmente se escolhe um único framework para evitar conflitos.

12. Onde encontro mais exemplos?

Visite a página oficial de docs.python.org ou o tutorial do medium.com.