@googleworkspace/cli

O que é googleworkspace-cli?

googleworkspace/cli (publicado como @googleworkspace/cli) é uma ferramenta de linha de comando para o Google Workspace. Ela permite trabalhar com várias APIs do Workspace — como Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin e mais — usando um único CLI.

A superfície de comandos é construída dinamicamente em tempo de execução a partir do Discovery Service do Google, em vez de enviar uma lista fixa de comandos. O projeto também é descrito como incluindo “habilidades para agentes de IA”, e o CLI enfatiza a saída em JSON estruturado para automação.

Principais Recursos

• Único CLI para vários serviços do Workspace: Fornece uma interface para interagir com Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin e outras APIs do Workspace.
• Geração dinâmica de comandos a partir do Discovery Service: Comandos e métodos são construídos lendo o Discovery Service do Google em tempo de execução, permitindo capturar novos endpoints/métodos sem uma lista estática de comandos.
• Saída em JSON estruturado: Projetado para uso com automação e agentes de IA; as respostas são retornadas em JSON estruturado.
• Introspecção de esquema para métodos de API: Use gws schema <...> para inspecionar o esquema de request/response de um método.
• Simulação de requests e auxiliares de paginação: Use --dry-run para pré-visualizar requests e --page-all para transmitir resultados paginados (opcionalmente para ferramentas como jq).
• Fluxos de autenticação múltiplos: Suporta fluxos de setup/login adequados para uso local, CI e servidores, incluindo integração com gcloud quando disponível.
• Habilidades de agente incluídas: A documentação do repositório nota que inclui “40+ habilidades para agentes”.

Como Usar o googleworkspace-cli

1. Instale o CLI:
   • Via npm: npm install -g @googleworkspace/cli
   • Ou usando um binário pré-compilado dos GitHub Releases
   • Ou compile a partir do fonte: cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux também mencionam Homebrew; flake do Nix está disponível.)
2. Autentique (setup do projeto uma vez, depois login):
   • gws auth setup (requer gcloud instalado e autenticado)
   • gws auth login (login OAuth subsequente)
   • Para fluxos manuais baseados em token ou console, a documentação lista variáveis de ambiente e um caminho de setup OAuth manual.
3. Execute comandos contra um recurso. Exemplos de fluxos da documentação incluem:
   • Listar arquivos: gws drive files list --params '{"pageSize": 5}'
   • Criar uma planilha: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Enviar uma mensagem no Chat: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • Introspecionar esquema: gws schema drive.files.list

Casos de Uso

• Automatize fluxos do Drive com paginação e JSON: Transmita grandes conjuntos de resultados de endpoints de listagem do Drive e processe-os com ferramentas downstream (ex.: combinando saída de --page-all com jq).
• Envie requests de Gmail/Chat/Calendar sem escrever chamadas REST raw: Use os comandos focados em recursos do CLI para criar ou atualizar objetos, confiando na interface gerada.
• Valide a estrutura do request antes de executar: Use --dry-run para pré-visualizar o que o CLI enviaria, ajudando ao gerar payloads para Sheets, Chat e outros recursos.
• Construa ferramentas para agentes de IA em torno de APIs do Workspace: Use respostas em JSON estruturado e as habilidades de agente incluídas para que um agente impulsionado por LLM decida quais ações do Workspace chamar com menos código customizado.
• Descubra como chamar um método de API pelo CLI: Quando você sabe que um método existe mas não o formato exato do request, use gws schema <method> para inspecionar o esquema de request/response.

FAQ

• O googleworkspace-cli é um produto oficial do Google? Não. O repositório nota: “Este não é um produto oficialmente suportado pelo Google.”

• Ele tem uma lista fixa de comandos? Não. A documentação afirma que não envia uma lista estática de comandos; ele lê o Discovery Service do Google em tempo de execução e constrói sua superfície de comandos dinamicamente.

• O que preciso instalar e executar? As pré-requisitos listam Node.js 18+ para o fluxo de instalação via npm. A autenticação requer um projeto Google Cloud para credenciais OAuth e uma conta Google com acesso ao Workspace.

• Qual setup de autenticação devo usar? A documentação descreve múltiplos caminhos:

  • Setup assistido por gcloud (gws auth setup) quando você tem gcloud instalado e autenticado
  • Setup OAuth manual via Google Cloud Console quando automação não é possível
  • Credenciais baseadas em token/manuais via variáveis de ambiente (conforme documentado)

• Há limitações relacionadas a scopes durante desenvolvimento/testes? Sim. A documentação avisa que, se o app OAuth estiver não verificado (modo de teste), o Google limita o consentimento a ~25 scopes e que o preset de escopo recomendado (85+ scopes) falhará para apps não verificados — especialmente para contas @gmail.com.

Alternativas

• Chamadas diretas à REST API com curl ou cliente HTTP: Permite chamar endpoints do Workspace diretamente, mas você precisa gerenciar formatação de requisições, paginação e detalhes de autenticação por conta própria.
• SDKs oficiais para serviços específicos do Workspace (ex.: bibliotecas de APIs do Google específicas de linguagem): Fornecem métodos de cliente tipados para serviços particulares, mas geralmente caminhos de código separados por API em vez de uma interface CLI dinâmica gerada.
• Outras ferramentas CLI para APIs do Google: CLIs alternativas podem focar em serviços específicos ou usar conjuntos de comandos estáticos; dependendo da ferramenta, elas podem não oferecer a mesma geração dinâmica de comandos baseada no Discovery Service ou fluxo de trabalho de JSON estruturado + introspecção de esquema descrito aqui.