====== Google Workspace CLI (gws) ======

//Vytvořeno: **14.6.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/googleworkspace/cli|Google Workspace CLI]] (příkaz ''gws'') je open-source CLI nástroj pro práci s Google Workspace API z terminálu. Pro AI část wiki je zajímavý hlavně tím, že vrací strukturovaný JSON, umí introspektovat API schémata a repozitář obsahuje Agent Skills pro Drive, Gmail, Calendar, Sheets, Docs, Chat a další služby. Projekt výslovně uvádí, že nejde o oficiálně podporovaný produkt Googlu a že před verzí 1.0 lze čekat breaking changes.

> **Poznámka:** Jde o rešeršní zápisek podle [[https://github.com/googleworkspace/cli/blob/main/README.md|README dokumentace projektu]]. Lokální otestování s vlastním Google účtem zde zatím není zaznamenané.

===== Co gws řeší =====

''gws'' poskytuje jedno CLI pro větší část ekosystému [[https://developers.google.com/workspace|Google Workspace]]. Místo ručního psaní REST volání načítá za běhu [[https://developers.google.com/discovery|Google Discovery Service]] a podle něj dynamicky staví dostupné příkazy.

Praktický dopad:

  * příkazová plocha není jen ručně udržovaný seznam endpointů,
  * když Google přidá metodu do Discovery dokumentů, ''gws'' ji může zpřístupnit bez ručního dopisování konkrétního příkazu,
  * výstup je strukturovaný JSON, takže se hodí do skriptů i pro AI agenty,
  * příkazy podporují ''--help'', ''--dry-run'', stránkování a introspekci schémat přes ''gws schema''.

===== Instalace =====

Doporučená instalace je stažení předpřipraveného binárního balíčku z [[https://github.com/googleworkspace/cli/releases|GitHub Releases]]. Alternativně lze použít [[https://www.npmjs.com/package/@googleworkspace/cli|npm balíček]], který stáhne odpovídající binárku, build z Rust zdrojů, Nix nebo Homebrew.

<code bash>
npm install -g @googleworkspace/cli
</code>

<code bash>
cargo install --git https://github.com/googleworkspace/cli --locked
</code>

<code bash>
nix run github:googleworkspace/cli
</code>

<code bash>
brew install googleworkspace-cli
</code>

Základní předpoklady podle dokumentace:

  * Node.js 18+ při instalaci přes npm,
  * Google Cloud projekt pro OAuth credentials,
  * Google účet s přístupem ke Google Workspace službám.

===== První spuštění a autentizace =====

Nejjednodušší lokální workflow je:

<code bash>
gws auth setup
gws auth login
gws drive files list --params '{"pageSize": 5}'
</code>

''gws auth setup'' provádí uživatele nastavením Google Cloud projektu a OAuth klienta. Pokud je OAuth aplikace v testing režimu, je potřeba přidat svůj účet mezi testovací uživatele. U neověřené aplikace je také limit počtu scope; dokumentace doporučuje vybrat jen služby, které jsou skutečně potřeba:

<code bash>
gws auth login -s drive,gmail,sheets
</code>

Pro headless nebo serverové použití dokumentace uvádí také práci s exportovanými credentials, service account souborem nebo předaným access tokenem přes proměnné prostředí:

<code bash>
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
</code>

===== Příklady použití =====

Vypsání posledních souborů z Drive:

<code bash>
gws drive files list --params '{"pageSize": 10}'
</code>

Vytvoření Google Sheets dokumentu:

<code bash>
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
</code>

Odeslání zprávy do Google Chatu s náhledem requestu bez skutečného provedení:

<code bash>
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run
</code>

Zjištění schématu konkrétní metody:

<code bash>
gws schema drive.files.list
</code>

Stránkovaný výstup jako NDJSON:

<code bash>
gws drive files list --params '{"pageSize": 100}' --page-all
</code>

===== Agent Skills a použití s AI agenty =====

Repozitář obsahuje [[https://github.com/googleworkspace/cli/blob/main/docs/skills.md|Skills Index]] s dovednostmi pro jednotlivé služby, helper příkazy, persony a recepty. To je hlavní důvod, proč článek patří do AI části: cílem není jen ruční CLI, ale i bezpečnější a strukturovanější ovládání Workspace služeb agentem.

Instalace všech skills:

<code bash>
npx skills add https://github.com/googleworkspace/cli
</code>

Instalace jen vybraných skills:

<code bash>
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail
</code>

Projekt obsahuje také [[https://github.com/googleworkspace/cli/blob/main/gemini-extension.json|Gemini CLI extension konfiguraci]]. Typický postup podle dokumentace:

<code bash>
gws auth setup
gemini extensions install https://github.com/googleworkspace/cli
</code>

Po instalaci extension může Gemini CLI agent volat ''gws'' příkazy a využít existující lokální autentizaci.

===== Helper příkazy =====

Kromě dynamicky generované příkazové plochy podle Discovery API obsahuje ''gws'' i ručně připravené helper příkazy s prefixem ''+''. Ty zjednodušují časté operace, například:

  * ''gws gmail +send'' — odeslání e-mailu,
  * ''gws gmail +reply'' a ''+reply-all'' — odpovědi s automatickým threadingem,
  * ''gws gmail +triage'' — přehled nepřečtené pošty,
  * ''gws calendar +agenda'' — agenda z kalendáře,
  * ''gws drive +upload'' — upload souboru,
  * ''gws workflow +standup-report'' — souhrn dnešních schůzek a úkolů,
  * ''gws workflow +meeting-prep'' — příprava na další schůzku.

Příklady:

<code bash>
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"
</code>

<code bash>
gws calendar +agenda
</code>

<code bash>
gws workflow +standup-report
</code>

===== Bezpečnost a omezení =====

Důležité body před praktickým nasazením:

  * Projekt není oficiálně podporovaný produkt Googlu.
  * Je ve vývoji před verzí 1.0, takže změny rozhraní jsou očekávatelné.
  * OAuth scope je potřeba držet co nejmenší. U agentů je to zvlášť důležité, protože nástroj může číst nebo měnit e-maily, soubory a kalendáře.
  * Pro destruktivnější akce je vhodné nejdřív používat ''--dry-run''.
  * Výstup na stdout je strukturovaný JSON; diagnostika a chyby patří na stderr, což je důležité pro skriptování.
  * [[https://github.com/googleworkspace/cli/blob/main/CHANGELOG.md|Changelog]] uvádí, že starší příkaz ''gws mcp'' byl ve verzi 0.8.0 odstraněn. Není tedy vhodné počítat s tím, že současná verze funguje jako MCP server.
  * Projekt podporuje integraci s [[https://cloud.google.com/security/products/model-armor|Google Cloud Model Armor]] pro sanitizaci promptů nebo odpovědí v agentních scénářích.

===== Kdy to dává smysl =====

''gws'' dává smysl tam, kde je potřeba Google Workspace ovládat skriptovatelně a zároveň čitelně pro agenta:

  * osobní nebo firemní automatizace nad Drive, Gmailem, Sheets a Kalendářem,
  * AI agent, který má připravovat meeting prep, triage inboxu nebo týdenní přehled,
  * rychlé prototypování bez psaní vlastního klienta proti Google API,
  * ladění Workspace API přes ''--dry-run'' a ''gws schema'',
  * workflow, kde je důležitý strojově čitelný JSON výstup.

===== Zdroje =====

  * [[https://github.com/googleworkspace/cli|googleworkspace/cli – GitHub repozitář]]
  * [[https://github.com/googleworkspace/cli/blob/main/README.md|README projektu]]
  * [[https://github.com/googleworkspace/cli/blob/main/docs/skills.md|Skills Index]]
  * [[https://github.com/googleworkspace/cli/blob/main/CHANGELOG.md|Changelog]]
  * [[https://github.com/googleworkspace/cli/releases|GitHub Releases]]
  * [[https://www.npmjs.com/package/@googleworkspace/cli|@googleworkspace/cli na npm]]
  * [[https://developers.google.com/discovery|Google Discovery Service]]
  * [[https://developers.google.com/workspace|Google Workspace Developer documentation]]
  * [[https://github.com/googleworkspace/cli/blob/main/gemini-extension.json|Gemini CLI extension konfigurace]]
  * [[https://cloud.google.com/security/products/model-armor|Google Cloud Model Armor]]