Gmail CLI

Uma ferramenta de linha de comando (CLI) robusta para interagir com o Gmail e Google Drive.

O diferencial deste projeto é sua arquitetura "Dual-Mode":

1. Modo Humano: Saída formatada com tabelas, cores e spinners (via Rich).
2. Modo Agente (IA): Saída em JSON limpo (--json) para ser consumido facilmente por LLMs e scripts.

🚀 Instalação

Como a ferramenta usa poetry e gerenciamento moderno, a instalação recomendada é via pipx para garantir isolamento e disponibilidade global no shell.

Pré-requisitos

• Python 3.10+
• pipx (sudo apt install pipx)

Instalando

pipx install git+https://github.com/ayrtonnotrya/gmail-cli.git

Após instalar, o comando gmail estará disponível no seu terminal.

🛠 Configuração (Primeiro Uso)

Antes de usar, você precisa autenticar com o Google.

1. Obtenha suas credenciais OAuth 2.0 no Google Cloud Console.

   💡 Dica: Para um passo-a-passo detalhado de como criar o projeto e habilitar as APIs, leia o Guia de Configuração (SETUP_GUIDE.md).

2. Baixe o arquivo credentials.json.
3. Execute o comando de login:

gmail auth login --credentials /caminho/para/credentials.json

Isso salvará o token de sessão de forma segura seguindo o padrão XDG (~/.config/gmail-cli/).

📖 Uso

Comandos Disponíveis

gmail --help                        # Exibe ajuda geral
gmail auth login                    # Autenticar com Google
gmail search <query>                # Buscar emails
gmail read <message_id>             # Ler email específico
gmail thread <message_id>           # Ver thread completa de um email
gmail download <msg_id> <att_id>    # Fazer download de anexo

Buscar E-mails

Modo Humano (Tabela Formatada)

gmail search "fatura cartão" --limit 5

Saída:

Searching for: fatura cartão
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID             ┃ Date               ┃ From             ┃ Subject              ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ 18abc123def456 │ 2025-11-15 10:30:0 │ banco@example.com│ Fatura do Cartão     │
│ 18abc789ghi012 │ 2025-11-10 14:20:1 │ loja@shop.com    │ Confirmação Cartão   │
└────────────────┴────────────────────┴──────────────────┴──────────────────────┘

Modo Agente (JSON Estruturado)

gmail search "projeto apollo" --since 7d --json

Saída:

[
  {
    "id": "18abc123def456",
    "date": "2025-11-15T10:30:00Z",
    "from": "team@company.com",
    "subject": "Update: Projeto Apollo"
  },
  {
    "id": "18abc789ghi012",
    "date": "2025-11-14T15:45:00Z",
    "from": "manager@company.com",
    "subject": "Re: Apollo - Next Steps"
  }
]

Queries Avançadas

# Emails não lidos
gmail search "is:unread" --limit 10

# Emails com anexos
gmail search "has:attachment" --json

# Emails de um remetente específico
gmail search "from:boss@company.com" --limit 5

# Combinação de critérios
gmail search "from:finance subject:invoice newer_than:30d" --json

# Emails importantes recentes
gmail search "is:important newer_than:7d" --limit 10

Deduplicação por Thread

Por padrão, o search retorna todos os emails que atendem à consulta. Se múltiplos emails da mesma thread correspondem, todos aparecem nos resultados. Use --first-per-thread para mostrar apenas o primeiro email de cada thread:

# Buscar emails, mostrando apenas o primeiro de cada thread
gmail search "projeto apollo" --first-per-thread

# Útil para depois usar o comando thread
gmail search "has:attachment" --first-per-thread --limit 20
# Agora você tem uma lista limpa de threads, escolha uma:
gmail thread <MESSAGE_ID>

# Combinação com outras flags
gmail search "from:cliente@empresa.com" --first-per-thread --since 30d --json

Benefícios:

• Resultados mais limpos (uma entrada por conversa)
• Facilita uso do comando thread posteriormente
• Cada thread aparece apenas uma vez, mesmo que múltiplos emails correspondam à query

Ler E-mail

Modo Humano (Formatado)

gmail read 18abc123def456

Saída:

Reading message: 18abc123def456
╭─────────────────── Email Details ───────────────────╮
│ Subject: Update: Projeto Apollo                     │
│ From: team@company.com                              │
│ Date: 2025-11-15T10:30:00Z                          │
╰─────────────────────────────────────────────────────╯

Body:
Olá equipe,

Segue atualização do projeto Apollo...

Modo Agente (JSON)

gmail read 18abc123def456 --json

Saída:

{
  "id": "18abc123def456",
  "subject": "Update: Projeto Apollo",
  "from": "team@company.com",
  "date": "2025-11-15T10:30:00Z",
  "body": "Olá equipe,\n\nSegue atualização do projeto Apollo...",
  "attachments": [
    {
      "filename": "report.pdf",
      "mimeType": "application/pdf",
      "size": 524288,
      "attachmentId": "ANGjdJ8xK9mN2pQ3r4s",
      "isInline": false
    }
  ]
}

Anexos e Imagens

O Gmail CLI agora exibe informações sobre anexos e imagens inline, incluindo:

• Nome do arquivo
• Tipo MIME
• Tamanho
• ID de anexo (para download futuro)

Modo Humano - Email com Anexo

gmail read 18abc123def456

Saída:

Reading message: 18abc123def456
╭─────────────────── Email Details ───────────────────╮
│ Subject: Monthly Report                             │
│ From: reports@company.com                           │
│ Date: 2025-11-15T10:30:00Z                          │
╰─────────────────────────────────────────────────────╯

Body:
Please find attached the monthly report.

Attachments:
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Filename   ┃ Type            ┃ Size   ┃ Attachment ID      ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ report.pdf │ application/pdf │ 512 KB │ ANGjdJ8xK9mN2pQ... │
└────────────┴─────────────────┴────────┴────────────────────┘

Modo Agente - Email com Anexo

gmail read 18abc123def456 --json

Saída:

{
  "id": "18abc123def456",
  "subject": "Monthly Report",
  "from": "reports@company.com",
  "date": "2025-11-15T10:30:00Z",
  "body": "Please find attached the monthly report.",
  "attachments": [
    {
      "filename": "report.pdf",
      "mimeType": "application/pdf",
      "size": 524288,
      "attachmentId": "ANGjdJ8xK9mN2pQ3r4sT5uV6w",
      "isInline": false
    }
  ]
}

Nota: Imagens inline (aquelas embutidas no corpo do email) são marcadas com "isInline": true e incluem um contentId para referência.

Download de Anexos

Você pode fazer download de anexos de duas formas: por Attachment ID ou por Filename (mais fácil!).

Método 1: Download por Filename (Recomendado)

A forma mais simples - basta saber o nome do arquivo:

# 1. Buscar emails com anexos
gmail search "has:attachment" --limit 5

# 2. Fazer download direto pelo nome do arquivo
gmail download <MESSAGE_ID> --by-name "report.pdf"

Exemplo:

gmail download 18abc123def456 --by-name "invoice.pdf"

Saída:

Downloading attachment...
Searching for attachment: invoice.pdf
╭─────────────── Attachment Downloaded ───────────────╮
│ ✓ Download successful!                              │
│                                                      │
│ File: invoice.pdf                                   │
│ Location: /home/user/Downloads/invoice.pdf          │
│ Size: 512.00 KB                                     │
╰──────────────────────────────────────────────────────╯

Com opções adicionais:

# Pasta customizada
gmail download <MSG_ID> --by-name "data.csv" --output-dir /tmp

# Modo JSON
gmail download <MSG_ID> --by-name "report.pdf" --json

Método 2: Download por Attachment ID

Alternativamente, você pode usar o attachment ID:

# 1. Buscar emails com anexos
gmail search "has:attachment" --limit 5

# 2. Ler o email e obter o Attachment ID
gmail read <MESSAGE_ID>

# 3. Fazer download do anexo
gmail download <MESSAGE_ID> <ATTACHMENT_ID>

Por padrão, os arquivos são salvos em ~/Downloads.

Download com Pasta Customizada

gmail download 18abc123def456 ANGjdJ8xK9mN2pQ3r4sT5uV6w --output-dir /tmp/attachments
# ou
gmail download 18abc123def456 --by-name "report.pdf" --output-dir /tmp/attachments

Download com Nome Customizado

gmail download 18abc123def456 ANGjdJ8xK9mN2pQ3r4sT5uV6w --filename relatorio_mensal.pdf

Modo Agente - Download JSON

gmail download 18abc123def456 --by-name "report.pdf" --json

Saída:

{
  "success": true,
  "filepath": "/home/user/Downloads/report.pdf",
  "filename": "report.pdf",
  "size": 524288,
  "message_id": "18abc123def456",
  "attachment_id": "ANGjdJ8xK9mN2pQ3r4sT5uV6w"
}

🤖 Exemplos para Agentes de IA

Criamos exemplos práticos de como agentes de IA podem usar o Gmail CLI:

• examples/agent_search.py - Buscar e processar emails em Python
• examples/agent_read.py - Ler emails e extrair informações
• examples/agent_workflow.sh - Workflow completo em Shell
• examples/llm_integration.py - Integração com LLMs

Veja mais detalhes em examples/README.md.

🔧 Troubleshooting

Erro de Autenticação

Problema: Error: credentials not found ou Token expired

Solução:

gmail auth login --credentials /caminho/para/credentials.json

Comando gmail não encontrado

Problema: Após instalação, o comando não está disponível

Solução:

# Certifique-se de que ~/.local/bin está no PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Ou reinstale
pipx install --force git+https://github.com/ayrtonnotrya/gmail-cli.git

Nenhum resultado na busca

Problema: Busca retorna lista vazia

Solução:

• Verifique se a query está correta
• Tente uma query mais ampla (ex: gmail search "is:inbox" --limit 5)
• Verifique se você tem permissão de leitura no Gmail

Erro ao ler email

Problema: Message not found

Solução:

• Verifique se o MESSAGE_ID está correto
• Use gmail search primeiro para obter IDs válidos
• Certifique-se de que você tem acesso ao email

💻 Desenvolvimento

git clone https://github.com/ayrtonnotrya/gmail-cli.git
cd gmail-cli
poetry install
poetry run gmail --help

🤝 Contribuição

Contribuições são bem-vindas! Por favor, leia nosso Guia de Contribuição para detalhes sobre nosso padrão de commits (PT-BR) e fluxo de desenvolvimento.

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais informações.