google-workspace-cli

name	google-workspace-cli
description	Administração do Google Workspace via CLI gws. Instale, autentique e automatize Gmail, Drive, Sheets, Calendar, Docs, Chat e Tasks. Execute auditorias de segurança, use 43 receitas integradas e 10 pacotes de persona. Use para administração do Google Workspace, configuração da CLI gws, automação do Gmail, gerenciamento do Drive ou agendamento de Calendar.
agents	["claude-code"]

Google Workspace CLI

Orientação especializada e automação para administração do Google Workspace usando a CLI gws de código aberto. Cobre instalação, autenticação, 18+ APIs de serviço, 43 receitas integradas e 10 pacotes de persona para fluxos de trabalho baseados em papel.

---

Início Rápido

Verificar Instalação

# Verificar se gws está instalado e autenticado
python3 scripts/gws_doctor.py

Enviar um E-mail

gws gmail users.messages send me --to "[e-mail]" \
  --subject "Weekly Update" --body "Here's this week's summary..."

Listar Arquivos do Drive

gws drive files list --json --limit 20 | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table

---

Instalação

npm (recomendado)

npm install -g @anthropic/gws
gws --version

Cargo (do código-fonte)

cargo install gws-cli
gws --version

Binários Pré-construídos

Baixe de github.com/googleworkspace/cli/releases para macOS, Linux ou Windows.

Verificar Instalação

python3 scripts/gws_doctor.py
# Verifica: PATH, versão, status de auth, conectividade de serviço

---

Autenticação

Configuração OAuth (Interativa)

# Passo 1: Criar projeto Google Cloud e credenciais OAuth
python3 scripts/auth_setup_guide.py --guide oauth

# Passo 2: Executar configuração de auth
gws auth setup

# Passo 3: Validar
gws auth status --json

Conta de Serviço (Headless/CI)

# Gerar instruções de configuração
python3 scripts/auth_setup_guide.py --guide service-account

# Configurar com arquivo de chave
export GWS_SERVICE_ACCOUNT_KEY=/path/to/key.json
export GWS_DELEGATED_USER=[e-mail]
gws auth status

Variáveis de Ambiente

# Gerar template .env
python3 scripts/auth_setup_guide.py --generate-env

Variável	Propósito
GWS_CLIENT_ID	ID de cliente OAuth
GWS_CLIENT_SECRET	Segredo de cliente OAuth
GWS_TOKEN_PATH	Caminho personalizado de armazenamento de token
GWS_SERVICE_ACCOUNT_KEY	Caminho da chave JSON da conta de serviço
GWS_DELEGATED_USER	Usuário a ser representado (contas de serviço)
GWS_DEFAULT_FORMAT	Formato de saída padrão (json/ndjson/table)

Validar Autenticação

python3 scripts/auth_setup_guide.py --validate --json
# Testa cada endpoint de serviço

---

Fluxo de Trabalho 1: Automação do Gmail

Objetivo: Automatizar operações de e-mail — enviar, pesquisar, rotular e gerenciar filtros.

Enviar e Responder

# Enviar um novo e-mail
gws gmail users.messages send me --to "[e-mail]" \
  --subject "Proposal" --body "Please find attached..." \
  --attachment proposal.pdf

# Responder a uma thread
gws gmail users.messages reply me --thread-id <THREAD_ID> \
  --body "Thanks for your feedback..."

# Encaminhar uma mensagem
gws gmail users.messages forward me --message-id <MSG_ID> \
  --to "[e-mail]"

Pesquisar e Filtrar

# Pesquisar e-mails
gws gmail users.messages list me --query "from:[e-mail] after:2025/01/01" --json \
  | python3 scripts/output_analyzer.py --count

# Listar rótulos
gws gmail users.labels list me --json

# Criar um filtro
gws gmail users.settings.filters create me \
  --criteria '{"from":"[e-mail]"}' \
  --action '{"addLabelIds":["Label_123"],"removeLabelIds":["INBOX"]}'

Operações em Massa

# Arquivar todos os e-mails lidos com mais de 30 dias
gws gmail users.messages list me --query "is:read older_than:30d" --json \
  | python3 scripts/output_analyzer.py --select "id" --format json \
  | xargs -I {} gws gmail users.messages modify me {} --removeLabelIds INBOX

---

Fluxo de Trabalho 2: Drive e Sheets

Objetivo: Gerenciar arquivos, criar planilhas, configurar compartilhamento e exportar dados.

Operações de Arquivo

# Listar arquivos
gws drive files list --json --limit 50 \
  | python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table

# Fazer upload de um arquivo
gws drive files create --name "Q1 Report" --upload report.pdf \
  --parents <FOLDER_ID>

# Criar uma Planilha Google
gws sheets spreadsheets create --title "Budget 2026" --json

# Baixar/exportar
gws drive files export <FILE_ID> --mime "application/pdf" --output report.pdf

Compartilhamento

# Compartilhar com usuário
gws drive permissions create <FILE_ID> \
  --type user --role writer --emailAddress "[e-mail]"

# Compartilhar com domínio (somente visualização)
gws drive permissions create <FILE_ID> \
  --type domain --role reader --domain "company.com"

# Listar quem tem acesso
gws drive permissions list <FILE_ID> --json

Dados do Sheets

# Ler um intervalo
gws sheets spreadsheets.values get <SHEET_ID> --range "Sheet1!A1:D10" --json

# Escrever dados
gws sheets spreadsheets.values update <SHEET_ID> --range "Sheet1!A1" \
  --values '[["Name","Score"],["Alice",95],["Bob",87]]'

# Adicionar linhas
gws sheets spreadsheets.values append <SHEET_ID> --range "Sheet1!A1" \
  --values '[["Charlie",92]]'

---

Fluxo de Trabalho 3: Calendar e Reuniões

Objetivo: Agendar eventos, encontrar horários disponíveis e gerar relatórios de standup.

Gerenciamento de Eventos

# Criar um evento
gws calendar events insert primary \
  --summary "Sprint Planning" \
  --start "2026-03-15T10:00:00" --end "2026-03-15T11:00:00" \
  --attendees "[e-mail]" \
  --location "Conference Room A"

# Listar próximos eventos
gws calendar events list primary --timeMin "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --maxResults 10 --json

# Evento rápido (linguagem natural)
gws helpers quick-event "Lunch with Sarah tomorrow at noon"

Encontrar Horário Disponível

# Verificar livre/ocupado para múltiplas pessoas
gws helpers find-time \
  --attendees "[e-mail],[e-mail],[e-mail]" \
  --duration 60 --within "2026-03-15,2026-03-19" --json

Relatório de Standup

# Gerar standup diário a partir do calendar + tasks
gws recipes standup-report --json \
  | python3 scripts/output_analyzer.py --format table

# Preparação para reunião (agenda + informações de participantes)
gws recipes meeting-prep --event-id <EVENT_ID>

---

Fluxo de Trabalho 4: Auditoria de Segurança

Objetivo: Auditar configuração de segurança do Google Workspace e gerar comandos de remediação.

Executar Auditoria Completa

# Auditoria completa em todos os serviços
python3 scripts/workspace_audit.py --json

# Auditar serviços específicos
python3 scripts/workspace_audit.py --services gmail,drive,calendar

# Modo demo (sem necessidade de gws)
python3 scripts/workspace_audit.py --demo

Verificações de Auditoria

Área	Verificação	Risco
Drive	Compartilhamento externo habilitado	Exfiltração de dados
Gmail	Regras de encaminhamento automático	Exfiltração de dados
Gmail	Registros DMARC/SPF/DKIM	Spoofing de e-mail
Calendar	Visibilidade de compartilhamento padrão	Vazamento de informações
OAuth	Concessões de apps de terceiros	Acesso não autorizado
Admin	Contagem de super administradores	Escalada de privilégio
Admin	Aplicação de verificação em 2 etapas	Tomada de conta

Revisar e Remediar

# Revisar resultados
python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py \
  --filter "status=FAIL" --select "area,check,remediation"

# Executar remediação (exemplo: restringir compartilhamento externo)
gws drive about get --json  # Verificar configurações atuais
# Seguir comandos de remediação da saída da auditoria

---

Ferramentas Python

Script	Propósito	Uso
gws_doctor.py	Diagnósticos pré-voo	python3 scripts/gws_doctor.py [--json] [--services gmail,drive]
auth_setup_guide.py	Configuração guiada de auth	python3 scripts/auth_setup_guide.py --guide oauth
gws_recipe_runner.py	Catálogo e executor de receitas	python3 scripts/gws_recipe_runner.py --list [--persona pm]
workspace_audit.py	Auditoria de segurança/config	python3 scripts/workspace_audit.py [--json] [--demo]
output_analyzer.py	Análise JSON/NDJSON	gws ... --json | python3 scripts/output_analyzer.py --count

Todos os scripts são somente stdlib, suportam saída --json e incluem modo demo com dados de amostra embutidos.

---

Melhores Práticas

Segurança

1. Use OAuth com escopos mínimos — solicite apenas o que cada fluxo de trabalho precisa
2. Armazene tokens no chaveiro do sistema, nunca em arquivos de texto simples
3. Rotacione chaves de conta de serviço a cada 90 dias
4. Audite concessões de apps OAuth de terceiros trimestralmente
5. Use --dry-run antes de operações destrutivas em massa

Automação

1. Canalize a saída --json por output_analyzer.py para filtragem e agregação
2. Use receitas para operações em múltiplas etapas em vez de encadear comandos brutos
3. Selecione um pacote de persona para escopo de receitas ao seu papel
4. Use NDformato JSON (--format ndjson) para streaming de grandes conjuntos de resultados
5. Defina GWS_DEFAULT_FORMAT=json no perfil do shell para scripts

Desempenho

1. Use --fields para solicitar apenas os campos necessários (reduz o tamanho do payload)
2. Use --limit para limitar resultados ao navegar
3. Use --page-all apenas quando precisar de datasets completos
4. Agrupe operações com receitas em vez de chamadas de API individuais
5. Armazene em cache dados frequentemente acessados (ex.: IDs de rótulo, IDs de pasta) em variáveis

---

Limitações

Restrição	Impacto
Tokens OAuth expiram após 1 hora	Re-auth necessária para scripts de longa duração
Limites de taxa de API (por usuário, por serviço)	Operações em massa podem atingir erros 429
Requisitos de escopo variam por serviço	Deve solicitar escopos corretos durante auth
Status de CLI pré-v1.0	Mudanças incompatíveis possíveis entre lançamentos
Projeto Google Cloud necessário	Gratuito, mas requer configuração no Cloud Console
Admin API precisa de privilégios de administrador	Algumas verificações de auditoria requerem papel de Admin do Workspace

Escopos Obrigatórios por Serviço

# Listar escopos para serviços específicos
python3 scripts/auth_setup_guide.py --scopes gmail,drive,calendar,sheets

Serviço	Escopos Principais
Gmail	gmail.modify, gmail.send, gmail.labels
Drive	drive.file, drive.metadata.readonly
Sheets	spreadsheets
Calendar	calendar, calendar.events
Admin	admin.directory.user.readonly, admin.directory.group
Tasks	tasks