Google Workspace CLI

GWS CLI: Jedno narzędzie do zarządzania całym ekosystemem Google Workspace

W dzisiejszym świecie automatyzacji i pracy opartej na danych, efektywne zarządzanie narzędziami biurowymi ma kluczowe znaczenie. GWS CLI (Google Workspace CLI) to nowoczesny interfejs wiersza poleceń, który konsoliduje dostęp do usług takich jak Google Drive, Gmail, Calendar, Sheets, Docs oraz Chat. Jest to rozwiązanie zbudowane z myślą o programistach, administratorach oraz agentach AI, które eliminuje potrzebę ręcznego pisania wywołań curl i analizowania obszernej dokumentacji REST.

Czym jest GWS CLI?

GWS CLI to uniwersalny interfejs CLI dla wszystkich usług Google Workspace. W przeciwieństwie do tradycyjnych narzędzi, gws nie posiada statycznej listy komend. Zamiast tego, w czasie rzeczywistym odczytuje Google Discovery Service, co pozwala mu na dynamiczne budowanie całej powierzchni poleceń. Gdy Google dodaje nowy punkt końcowy API lub metodę, GWS CLI wykrywa to automatycznie, zapewniając użytkownikom zawsze aktualne narzędzie.

Narzędzie to zostało zaprojektowane tak, aby było przyjazne zarówno dla ludzi, jak i dla maszyn. Każda odpowiedź jest zwracana jako ustrukturyzowany format JSON, co czyni je idealnym fundamentem dla skryptów oraz agentów LLM (Large Language Models).

Kluczowe cechy GWS CLI

• Dynamiczna architektura: Wykorzystuje Discovery Service do automatycznego generowania komend dla każdego API Workspace.
• Stworzony dla AI: Zawiera ponad 100 umiejętności agenta (Agent Skills) i rozszerzenie dla Gemini CLI, co pozwala modelom AI zarządzać Workspace bez dedykowanego kodu.
• Zero Boilerplate: Automatyczna paginacja, wsparcie dla przesyłania plików (multipart uploads) oraz czytelna pomoc --help dla każdego zasobu.
• Bezpieczeństwo: Obsługuje szyfrowane poświadczenia (AES-256-GCM) w systemowym pęku kluczy oraz różne przepływy OAuth2.
• Wsparcie dla wielu usług: Obsługuje Gmail, Drive, Calendar, Sheets, Chat, Admin i wiele innych.
• Helper Commands: Specjalne polecenia z prefiksem + (np. +send, +agenda) upraszczające najczęstsze zadania.

Przypadki użycia (Use Case)

1. Automatyzacja raportów w Google Sheets

Zamiast ręcznie wprowadzać dane, możesz użyć GWS CLI do dopisywania wierszy do arkusza kalkulacyjnego bezpośrednio z logów systemowych lub skryptów CI/CD.

2. Zarządzanie plikami w Google Drive

Szybkie przesyłanie dokumentów, listowanie plików z filtrowaniem oraz zarządzanie uprawnieniami bez opuszczania terminala.

3. Integracja z Agentami AI

Dzięki rozszerzeniu dla Gemini CLI, Twój agent AI może otrzymać dostęp do poczty Gmail, kalendarza i dokumentów, co pozwala mu na np. streszczanie porannej agendy lub wysyłanie odpowiedzi na e-maile.

4. Headless / CI/CD

Użycie plików poświadczeń lub tokenów dostępu pozwala na bezpieczne uruchamianie operacji na Google Workspace w środowiskach serwerowych i potokach wdrożeniowych.

Jak używać GWS CLI?

Instalacja

Najprostszym sposobem instalacji jest użycie menedżera pakietów npm:

npm install -g @googleworkspace/cli

Dostępne są również binaria dla systemu Rust (cargo), Homebrew oraz Nix.

Konfiguracja i logowanie

Pierwszym krokiem jest konfiguracja projektu w Google Cloud:

1. Uruchom gws auth setup, aby skonfigurować projekt i włączyć API.
2. Użyj gws auth login, aby przejść przez proces autoryzacji OAuth.

Przykładowe polecenia

• Listowanie plików w Drive: gws drive files list --params '{"pageSize": 10}'
• Wysyłanie wiadomości w Chat: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Zadanie wykonane"}'
• Sprawdzenie agendy: gws calendar +agenda
• Wysyłanie maila: gws gmail +send --to [email protected] --subject "Raport" --body "Treść wiadomości"

Często zadawane pytania (FAQ)

Czy GWS CLI jest oficjalnym produktem Google?

Nie, jest to projekt rozwijany przez społeczność i pracowników Google, ale nie jest to oficjalnie wspierany produkt Google.

Dlaczego widzę błąd "Access blocked" podczas logowania?

Najprawdopodobniej Twoja aplikacja OAuth jest w trybie testowym. Musisz dodać swój adres e-mail do sekcji "Test users" w konsoli Google Cloud.

Jak obsługiwane są strefy czasowe w kalendarzu?

Pomocnicze komendy, takie jak +agenda, automatycznie pobierają strefę czasową z ustawień Twojego konta Google i zapisują ją w pamięci podręcznej na 24 godziny.

Czy mogę używać GWS CLI na serwerze bez przeglądarki?

Tak. Możesz wyeksportować poświadczenia za pomocą gws auth export na maszynie z przeglądarką, a następnie użyć zmiennej środowiskowej GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE na serwerze.

Co oznaczają kody wyjścia (Exit Codes)?

• 0: Sukces.
• 1: Błąd API Google.
• 2: Błąd autoryzacji.
• 3: Błąd walidacji parametrów.
• 4: Błąd usługi Discovery.