gws: ein auf dem Discovery Service aufbauendes Kommandozeilen-Tool für Google Workspace

Eine zur Laufzeit generierte Befehlsfläche

gws ist ein in Rust geschriebenes Kommandozeilen-Tool, das Google Workspace APIs über eine einzige Schnittstelle bereitstellt. Statt eine feste Befehlsliste auszuliefern, liest es zur Laufzeit den Google Discovery Service und baut seinen Befehlsbaum aus den Dienst-Dokumenten auf. Wenn Google eine Methode hinzufügt, übernimmt gws sie ohne Release. Die README stellt fest, dass jede Antwort strukturiertes JSON ist, und das Tool ist sowohl für interaktive Nutzung als auch für KI-Agenten konzipiert. Das Repository ist kein offiziell unterstütztes Google-Produkt und befindet sich in aktiver Entwicklung, mit breaking changes vor 1.0.

Installationswege und Voraussetzungen

Die empfohlene Installation ist eine vorkompilierte Binärdatei von der GitHub Releases Seite, die in den PATH gelegt wird. Zur Bequemlichkeit kann npm das Herunterladen automatisieren: npm install -g @googleworkspace/cli. Quellcode-Builds verwenden cargo install --git ... mit --locked. Ein Nix Flake ist unter github:googleworkspace/cli verfügbar, und macOS/Linux-Nutzer können über Homebrew installieren. Voraussetzungen umfassen Node.js 18+ bei npm-Nutzung, ein Google Cloud-Projekt für OAuth-Anmeldedaten und ein Google-Konto mit Workspace-Zugriff. Die README nennt keine Mindestversionen für den reinen Binärpfad.

Schnellstart und typische Befehle

Nach der Installation führen Sie gws auth setup aus, um die Projektkonfiguration durchzugehen, dann gws auth login für OAuth. Der Schnellstart zeigt gws drive files list --params '{"pageSize": 5}'. Weitere Beispiele umfassen das Erstellen einer Tabelle mit gws sheets spreadsheets create --json, das Senden einer Chat-Nachricht mit --dry-run, das Prüfen von Schemata mit gws schema drive.files.list und das Streamen von paginierten Ergebnissen mit --page-all. Alle Beispiele verwenden einfache Anführungszeichen um JSON-Argumente wegen Shell-Escaping, was bei Sheets-Bereichen mit Ausrufezeichen wichtig ist.

Authentifizierungs-Workflows

Die CLI unterstützt mehrere Authentifizierungswege. Mit installiertem gcloud kann gws auth setup ein Projekt erstellen, APIs aktivieren und sich anmelden. Ohne gcloud wird das manuelle OAuth-Setup in der Cloud Console dokumentiert, einschließlich des Hinzufügens als Testbenutzer. Für headless oder CI-Umgebungen erzeugt gws auth export --unmasked Anmeldedaten, die über die Umgebungsvariable GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE geladen werden können. Dienstkonten zeigen dieselbe Variable auf eine Schlüsseldatei. Ein vorab erlangtes Zugriffstoken kann mit GOOGLE_WORKSPACE_CLI_TOKEN übergeben werden. Die Reihenfolge ist Token, Anmeldedatendatei, verschlüsselte Login-Anmeldedaten, dann Klartext-Anmeldedaten. Die README warnt, dass unverifizierte OAuth-Apps auf etwa 25 Scopes begrenzt sind, während das empfohlene Preset 85+ enthält.

Agent-Fähigkeiten und Integrationen

Das Repository enthält über 100 Agent-Fähigkeiten, jede als SKILL.md-Datei, die alle unterstützten APIs sowie übergeordnete Workflow-Helfer und 50 kuratierte Rezepte für Gmail, Drive, Docs, Calendar und Sheets abdeckt. Fähigkeiten können mit npx skills add für das gesamte Repository oder einzelne Dienstverzeichnisse installiert werden. Ein OpenClaw-Setup wird mit Symlinks zu ~/.openclaw/skills/ beschrieben. Eine Gemini CLI-Erweiterung ist über gemini extensions install verfügbar, die dem Agenten nach einmaliger Authentifizierung Zugriff auf gws-Befehle gibt. Die README erläutert nicht, wie Fähigkeiten ausgeführt werden oder welche Laufzeit sie benötigen.

Erweiterte Nutzung: Helfer, Pagination und Sanitization

Über die Discovery-generierten Methoden hinaus bietet gws handgefertigte Helferbefehle mit +-Präfix, wie gmail +send, calendar +agenda, drive +upload und workflow +standup-report. Sie erscheinen neben den automatisch generierten Befehlen in der Hilfe. Die Pagination wird mit --page-all für NDJSON-Streaming, --page-limit und --page-delay gesteuert. Multipart-Uploads erfolgen mit --upload bei drive files create. Bei Google Sheets müssen Bereiche in einfache Anführungszeichen gesetzt werden, um Shell-History-Expansion zu vermeiden. Die Model-Armor-Integration ist über --sanitize bei API-Aufrufen verfügbar, mit Umgebungsvariablen für Standardvorlage und Modus.

Exit-Codes, Architektur und Fehlerbehebung

gws verwendet strukturierte Exit-Codes: 0 Erfolg, 1 API-Fehler, 2 Authentifizierungsfehler, 3 Validierungsfehler, 4 Discovery-Fehler, 5 interner Fehler. Die Architektur ist zweistufiges Parsen: Zuerst den Dienst aus argv identifizieren, das Discovery-Dokument abrufen (24 Stunden gecacht), einen clap-Befehlsbaum aufbauen, Argumente erneut parsen, authentifizieren und ausführen. Alle Ausgaben sind JSON. Die Fehlerbehebung behandelt häufige Login-Fehler: Testmodus-Einschränkungen, Scope-Limits, fehlendes gcloud, redirect_uri_mismatch und nicht aktivierte API. Entwicklung nutzt cargo build, clippy, test und ein Coverage-Skript. Die Lizenz ist Apache-2.0; die README bietet darüber hinaus keine Garantie- oder Support-Bedingungen.

Redaktionelles Fazit

Die README enthält keine Angaben zu stabiler Version oder Support-Garantie; das Projekt ist aktiv in Entwicklung, breaking changes sind zu erwarten. Für cli sollte der konkrete README-Einstieg mit den eigenen Eingaben geprüft werden; diese Einordnung behauptet keine Ergebnisse aus einem eigenen Lauf.

Offizielle Quellen

1. Official documentation
2. Official README
3. Project repository
4. Release notes