@googleworkspace/cli

Was ist googleworkspace-cli?

googleworkspace/cli (veröffentlicht als @googleworkspace/cli) ist ein Befehlszeilentool für Google Workspace. Es ermöglicht die Arbeit mit mehreren Workspace-APIs – wie Drive, Gmail, Kalender, Sheets, Docs, Chat, Admin und mehr – über eine einzige CLI.

Die Befehlsoberfläche wird zur Laufzeit dynamisch erstellt aus Googles Discovery Service, statt eine feste Liste von Befehlen mitzuliefern. Das Projekt wird auch als inklusive „AI agent skills“ beschrieben, und die CLI betont strukturierte JSON-Ausgabe für Automatisierung.

Wichtige Funktionen

• Eine CLI für mehrere Workspace-Dienste: Bietet eine einzige Oberfläche für die Interaktion mit Drive, Gmail, Kalender, Sheets, Docs, Chat, Admin und anderen Workspace-APIs.
• Dynamische Befehlserstellung aus Discovery Service: Befehle und Methoden werden zur Laufzeit durch Auslesen von Googles Discovery Service erstellt, sodass neue Endpunkte/Methoden ohne statische Befehlsliste erfasst werden.
• Strukturierte JSON-Ausgabe: Entwickelt für Automatisierung und AI-Agenten; Antworten werden als strukturiertes JSON zurückgegeben.
• Schema-Introspektion für API-Methoden: Verwenden Sie gws schema <...>, um das Request/Response-Schema einer Methode zu inspizieren.
• Request-Simulation und Pagination-Helfer: Verwenden Sie --dry-run, um Requests vorab zu prüfen, und --page-all, um paginierte Ergebnisse zu streamen (optional zu Tools wie jq).
• Mehrere Authentifizierungsworkflows: Unterstützt Setup-/Login-Workflows für lokalen Einsatz, CI und Server, inklusive Integration mit gcloud, falls verfügbar.
• Bundled agent skills: Die Repository-Dokumentation vermerkt, dass es „40+ agent skills“ enthält.

So verwenden Sie googleworkspace-cli

1. Installieren Sie die CLI:
   • Via npm: npm install -g @googleworkspace/cli
   • Oder mit einem vorgefertigten Binary aus GitHub Releases
   • Oder aus dem Quellcode bauen: cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux: Auch Homebrew erwähnt; Nix-Flake verfügbar.)
2. Authentifizieren (einmalige Projekt-Setup, dann Login):
   • gws auth setup (erfordert installiertes und authentifiziertes gcloud)
   • gws auth login (folgender OAuth-Login)
   • Für manuelle Token- oder Console-basierte Flows listen die Docs Umgebungsvariablen und einen manuellen OAuth-Setup-Pfad auf.
3. Befehle gegen eine Ressource ausführen. Beispiele aus den Docs:
   • Dateien auflisten: gws drive files list --params '{"pageSize": 5}'
   • Spreadsheet erstellen: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Chat-Nachricht senden: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • Schema introspezieren: gws schema drive.files.list

Anwendungsfälle

• Drive-Workflows mit Pagination und JSON automatisieren: Große Ergebnismengen aus Drive-List-Endpoints streamen und mit Downstream-Tools verarbeiten (z. B. --page-all-Ausgabe mit jq kombinieren).
• Gmail/Chat/Kalender-Requests ohne rohe REST-Calls senden: CLI-Ressourcen-Befehle nutzen, um Objekte zu erstellen oder zu aktualisieren, basierend auf der generierten Oberfläche.
• Request-Struktur vor Ausführung validieren: --dry-run verwenden, um zu prüfen, was die CLI senden würde – hilfreich bei Payloads für Sheets, Chat und andere Ressourcen.
• AI-Agent-Tooling um Workspace-APIs bauen: Strukturierte JSON-Antworten und inkludierte Agent-Skills nutzen, damit ein LLM-gesteuerter Agent Workspace-Aktionen mit weniger Custom-Code aufruft.
• API-Methode über CLI entdecken: Wenn Sie eine Methode kennen, aber nicht die genaue Request-Form, gws schema <method> für Request/Response-Schema nutzen.

FAQ

• Ist googleworkspace-cli ein offizielles Google-Produkt? Nein. Das Repository vermerkt: „This is not an officially supported Google product.“

• Hat es eine feste Befehlsliste? Nein. Die Docs stellen klar, dass es keine statische Befehlsliste mitliefert; es liest zur Laufzeit Googles Discovery Service und erstellt die Befehlsoberfläche dynamisch.

• Was brauche ich zur Installation und Ausführung? Die Voraussetzungen listen Node.js 18+ für den npm-Installationspfad auf. Authentifizierung erfordert ein Google Cloud-Projekt für OAuth-Credentials und ein Google-Konto mit Workspace-Zugriff.

• Welchen Authentifizierungs-Setup soll ich wählen? Die Docs beschreiben mehrere Pfade:

  • gcloud-unterstütztes Setup (gws auth setup), wenn gcloud installiert und authentifiziert ist
  • Manuelles OAuth-Setup via Google Cloud Console, wenn Automatisierung nicht möglich
  • Token-basierte/manuelle Credentials via Umgebungsvariablen (wie dokumentiert)

• Gibt es scope-bezogene Einschränkungen in Entwicklung/Tests? Ja. Die Docs warnen, dass bei unverifizierter OAuth-App (Testmodus) Google die Zustimmung auf ~25 Scopes beschränkt und dass das empfohlene Scope-Preset (85+ Scopes) bei unverifizierten Apps scheitert – besonders bei @gmail.com-Konten.

Alternativen

• Direkte REST-API-Aufrufe mit curl oder einem HTTP-Client: Ermöglicht direkte Aufrufe von Workspace-Endpunkten, aber Sie müssen Request-Formatierung, Pagination und Authentifizierungsdetails selbst verwalten.
• Offizielle SDKs für spezifische Workspace-Dienste (z. B. sprachspezifische Google-APIs-Bibliotheken): Bieten typisierte Client-Methoden für bestimmte Dienste, aber in der Regel separate Codepfade pro API statt einer einzigen dynamisch generierten CLI-Schnittstelle.
• Andere CLI-Tools für Google APIs: Alternative CLIs konzentrieren sich möglicherweise auf spezifische Dienste oder verwenden statische Befehlssets; je nach Tool bieten sie nicht dieselbe dynamische Discovery-Service-gesteuerte Befehlserzeugung oder den strukturierten JSON- + Schema-Introspektion-Workflow wie hier beschrieben.