@googleworkspace/cli

Cos'è googleworkspace-cli?

googleworkspace/cli (pubblicato come @googleworkspace/cli) è uno strumento da riga di comando per Google Workspace. Ti permette di lavorare con molteplici API di Workspace — come Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin e altre — utilizzando un'unica CLI.

L'interfaccia dei comandi è generata dinamicamente all'avvio dal Discovery Service di Google, anziché spedire una lista fissa di comandi. Il progetto include anche “AI agent skills” e la CLI enfatizza l'output JSON strutturato per l'automazione.

Caratteristiche principali

• Unica CLI per più servizi Workspace: Fornisce un'interfaccia unica per interagire con Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin e altre API di Workspace.
• Generazione dinamica comandi dal Discovery Service: I comandi e i metodi vengono costruiti leggendo il Discovery Service di Google all'avvio, così i nuovi endpoint/metodi sono rilevati senza una lista statica di comandi.
• Output JSON strutturato: Progettato per l'uso con automazione e agenti AI; le risposte sono restituite in JSON strutturato.
• Introspezione schema per metodi API: Usa gws schema <...> per ispezionare lo schema richiesta/risposta di un metodo.
• Simulazione richieste e helper paginazione: Usa --dry-run per anteprimere le richieste e --page-all per trasmettere risultati paginati (opzionalmente a tool come jq).
• Workflow di autenticazione multipli: Supporta setup/login adatti per uso locale, CI e server, inclusa l'integrazione con gcloud quando disponibile.
• Skills agente inclusi: La documentazione del repository nota che include “40+ agent skills”.

Come usare googleworkspace-cli

1. Installa la CLI:
   • Via npm: npm install -g @googleworkspace/cli
   • O usando un binario pre-compilato da GitHub Releases
   • O compila da sorgente: cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux supportano anche Homebrew; disponibile Nix flake.)
2. Autentica (setup progetto una tantum, poi login):
   • gws auth setup (richiede gcloud installato e autenticato)
   • gws auth login (login OAuth successivo)
   • Per flussi manuali basati su token o console, la documentazione elenca variabili d'ambiente e un percorso di setup OAuth manuale.
3. Esegui comandi su una risorsa. Esempi di workflow dalla documentazione:
   • Elenca file: gws drive files list --params '{"pageSize": 5}'
   • Crea foglio di lavoro: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Invia messaggio Chat: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • Introspezione schema: gws schema drive.files.list

Casi d'uso

• Automatizza workflow Drive con paginazione e JSON: Trasmetti grandi insiemi di risultati da endpoint Drive list e processali con tool downstream (es. combinando output --page-all con jq).
• Invia richieste Gmail/Chat/Calendar senza REST raw: Usa i comandi resource-focused della CLI per creare o aggiornare oggetti affidandoti all'interfaccia generata.
• Valida struttura richiesta prima dell'esecuzione: Usa --dry-run per anteprimere cosa invierebbe la CLI, utile per generare payload per Sheets, Chat e altre risorse.
• Costruisci tooling per agenti AI intorno alle API Workspace: Usa risposte JSON strutturate e le agent skills incluse così un agente LLM-driven può decidere quali azioni Workspace chiamare con meno codice custom.
• Scopri come chiamare un metodo API dalla CLI: Quando conosci un metodo ma non la forma esatta della richiesta, usa gws schema <method> per ispezionare lo schema richiesta/risposta.

FAQ

• googleworkspace-cli è un prodotto ufficiale Google? No. Il repository specifica: “This is not an officially supported Google product.”

• Ha una lista fissa di comandi? No. La documentazione afferma che non spedisce una lista statica di comandi; legge il Discovery Service di Google all'avvio e genera dinamicamente l'interfaccia comandi.

• Cosa serve per installarlo e usarlo? I prerequisiti includono Node.js 18+ per il flusso npm. L'autenticazione richiede un progetto Google Cloud per credenziali OAuth e un account Google con accesso Workspace.

• Quale setup di autenticazione usare? La documentazione descrive più percorsi:

  • Setup assistito gcloud (gws auth setup) quando hai gcloud installato e autenticato
  • Setup OAuth manuale via Google Cloud Console quando l'automazione non è possibile
  • Credenziali token-based/manuali via variabili d'ambiente (come documentato)

• Ci sono limitazioni scope-related in sviluppo/test? Sì. La documentazione avverte che se l'app OAuth è non verificata (modalità test), Google limita il consenso a ~25 scope e che il preset scope raccomandato (85+ scope) fallirà per app non verificate — specialmente per account @gmail.com.

Alternative

• Chiamate dirette REST API con curl o un client HTTP: Ti permette di chiamare direttamente gli endpoint di Workspace, ma devi gestire da solo formattazione delle richieste, paginazione e dettagli di autenticazione.
• SDK ufficiali per servizi Workspace specifici (es. librerie Google APIs specifiche per linguaggio): Forniscono metodi client tipizzati per servizi particolari, ma tipicamente percorsi di codice separati per API anziché un'unica interfaccia CLI generata dinamicamente.
• Altri tool CLI per Google APIs: CLIs alternative potrebbero concentrarsi su servizi specifici o usare insiemi di comandi statici; a seconda del tool, potrebbero non offrire la stessa generazione dinamica di comandi basata su Discovery Service o workflow di JSON strutturato + introspezione schema descritto qui.