DEV Community

Cover image for Como Usar e Aproveitar ao Máximo o Google Workspace CLI
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar e Aproveitar ao Máximo o Google Workspace CLI

#google #cli #productivity #tooling

Google Workspace CLI (invocado como gws) é uma ferramenta de linha de comando open source que unifica o acesso a Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin e todas as APIs do Google Workspace. Ele é construído diretamente sobre o Discovery Service do Google, mantendo comandos sempre atualizados sem necessidade de atualizar a ferramenta. Instale globalmente via npm, autentique-se uma vez com OAuth e conecte-se a agentes como Claude Code ou Cursor com habilidades pré-instaladas. Não são necessários SDKs separados nem fluxos customizados de OAuth.

Experimente o Apidog hoje

Por que usar o Google Workspace CLI?

Ao automatizar tarefas no Google Workspace (como manipular arquivos no Drive, enviar emails, criar eventos ou editar documentos), normalmente você lida com scripts curl, escopos OAuth complicados, paginação manual e SDKs que rapidamente ficam desatualizados. Cada serviço tem APIs, fluxos de autenticação e detalhes próprios, gerando muito código repetitivo e manutenção.

O Google Workspace CLI resolve isso ao descobrir dinamicamente todos os métodos do Workspace em tempo real via Discovery Service. Assim, você sempre tem acesso aos endpoints mais recentes, sem precisar atualizar nada.

Benefícios principais:

  • Scripts e automações sempre atualizados.
  • Gera JSON limpo.
  • Suporte a dry-runs, paginação automática, e mais de 40 atalhos (prefixados com +), como gws gmail +send ou gws calendar +agenda.
  • Pronto para agentes de IA: Claude Code, Cursor, Gemini CLI etc.

Combine com Apidog: Enquanto o Google Workspace CLI conecta você às APIs, o Apidog permite testar, depurar e automatizar testes das suas integrações.

Instalação rápida do Google Workspace CLI

Pré-requisito: Node.js 18+

Verifique sua versão:

node --version
Enter fullscreen mode Exit fullscreen mode

Rodar sem instalar:

Use npx para testar rapidamente:

npx @googleworkspace/cli --help
npx @googleworkspace/cli drive files list --params '{"pageSize":1}'
Enter fullscreen mode Exit fullscreen mode

Ideal para experimentação ou scripts pontuais.

Instalar globalmente:

Para uso recorrente, instale global:

npm install -g @googleworkspace/cli
gws --version
Enter fullscreen mode Exit fullscreen mode

O binário já vem pré-compilado. Alternativas: baixe via GitHub Releases, instale por Homebrew (brew install googleworkspace/cli) ou rode via Nix.

Configuração e autenticação

Setup inicial guiado:

O comando abaixo cuida de criar projetos, habilitar APIs e OAuth:

gws auth setup
Enter fullscreen mode Exit fullscreen mode

Isso abre seu navegador, cria o projeto no Google Cloud se necessário, habilita APIs e armazena as credenciais localmente de forma segura (AES-256-GCM).

Instalar habilidades para agentes de IA:

Após configurar, instale habilidades de agente:

npx skills add https://github.com/googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

Ou use instaladores próprios do agente (Claude Code, Cursor, etc). Reinicie o agente para carregar os comandos do Google Workspace CLI.

Configuração global ou por projeto:

Por padrão, a configuração é global. Para escopo somente do projeto:

gws auth setup --project
Enter fullscreen mode Exit fullscreen mode

Gerenciar autenticação:

  • Reautenticar ou trocar de conta: 
  gws auth login
Enter fullscreen mode Exit fullscreen mode
  • Ver usuário/autorização atual: 
  gws auth whoami
Enter fullscreen mode Exit fullscreen mode
  • Desconectar: 
  gws auth logout
Enter fullscreen mode Exit fullscreen mode
  • Para uso em CI/headless, exporte as credenciais: 
  gws auth export --unmasked > creds.json
  export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json
Enter fullscreen mode Exit fullscreen mode

Ou use token do gcloud:

  export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
Enter fullscreen mode Exit fullscreen mode

Desativar telemetria:

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

Comandos práticos: Drive, Gmail, Calendar, Sheets, Docs, Chat

O CLI descobre comandos dinamicamente. Veja os serviços e comandos disponíveis:

gws --help
Enter fullscreen mode Exit fullscreen mode

Exemplos rápidos

Drive

  • Listar arquivos recentes: 
  gws drive files list --params '{"pageSize":10, "q":"name contains report"}'
Enter fullscreen mode Exit fullscreen mode
  • Fazer upload: 
  gws drive +upload ./budget.xlsx --name "2026 Budget"
Enter fullscreen mode Exit fullscreen mode

Gmail

  • Enviar email: 
  gws gmail +send --to colega@example.com --subject "Atualização" --body "Veja anexo." --attach ./arquivo.pdf
Enter fullscreen mode Exit fullscreen mode
  • Responder ou triar inbox: 
  gws gmail +reply --message-id <ID> --body "Obrigado!"
  gws gmail +triage
Enter fullscreen mode Exit fullscreen mode

Calendar

  • Criar evento: 
  gws calendar +insert --summary "Sprint Planning" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "equipe@example.com"
Enter fullscreen mode Exit fullscreen mode
  • Ver agenda de hoje: 
  gws calendar +agenda --today
Enter fullscreen mode Exit fullscreen mode

Sheets

  • Adicionar linha: 
  gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Tarefa X,Feita,2026-03-16"
Enter fullscreen mode Exit fullscreen mode

Docs

  • Inserir texto: 
  gws docs +write --documentId <ID> --text "Nova seção adicionada via Google Workspace CLI"
Enter fullscreen mode Exit fullscreen mode

Chat

  • Postar mensagem: 
  gws chat +send --space <SPACE_ID> --text "Deploy concluído 🚀"
Enter fullscreen mode Exit fullscreen mode

Use --dry-run para simular chamadas de API sem executar. Adicione --page-all para paginação completa como NDJSON.

Configuração avançada

Persista opções com variáveis de ambiente ou arquivo .env:

export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'
Enter fullscreen mode Exit fullscreen mode

Ajuste timeouts, formatos (--json, --yaml), use chaveiro por arquivo, etc.

Verifique configurações atuais:

gws config
Enter fullscreen mode Exit fullscreen mode

Integração com agentes de IA e prompts

Depois de instalar as habilidades, agentes podem invocar o Google Workspace CLI diretamente.

Prompt padrão:

  • “Liste meus arquivos recentes do Drive usando Google Workspace CLI.”
  • “Envie um e-mail de acompanhamento via Google Workspace CLI.”

Regra automática para agentes:

Inclua nas instruções do agente (CLAUDE.md, Cursor rules, etc):

"Sempre que a tarefa envolver Gmail, Drive, Calendar, Sheets, Docs ou Chat, use os comandos do Google Workspace CLI automaticamente antes de responder. Resolva o serviço e o método primeiro."

Agentes retornam arquivos/resultados JSON mantendo o contexto enxuto.

Testando integrações com Apidog

O Google Workspace CLI facilita o acesso, mas para depurar payloads, escopos e respostas, use o Apidog. Com ele, você pode:

  • Enviar requisições de teste (ex: Sheets.values.append).
  • Visualizar e depurar escopos (ex: envio no Gmail).
  • Armazenar chaves/tokens como variáveis e alternar entre contas.

Exemplos de workflow:

  • Agente pede adicionar linha na planilha → Teste o payload no Apidog antes.
  • Problemas de escopo no Gmail → Monte e execute a requisição no Apidog.
  • Troque entre contas/variáveis para validar integrações.

Google Workspace CLI + Apidog = APIs do Workspace ao vivo + testes automatizados e confiáveis.

FAQ

O Google Workspace CLI envia meus dados externamente?

Não. Suas chamadas vão diretamente para as APIs do Google. Seus dados ficam na sua conta Google.

Quais serviços são suportados?

Todas as APIs do Workspace (Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Script etc.), descobertas dinamicamente.

Comandos ficam atualizados?

Sim. Sempre atualizado via Discovery Service do Google em tempo real.

Precisa de chave de API?

Não. Usa OAuth padrão ou contas de serviço – basta autenticar.

Quais agentes/editores são suportados?

Claude Code, Cursor, OpenClaw, Gemini CLI, VS Code (MCP ou Agent Skills).

Diferença entre comandos brutos e + auxiliares?

Brutos = métodos exatos da API (ex: drive.files.list).

  • Auxiliares = atalhos para tarefas comuns (ex: +upload, +send).

Posso usar sem agente de IA?

Sim! Perfeito para scripts, automação ou uso direto no terminal.

Recursos adicionais

Top comments (0)