Google Workspace CLI (gws)

Toto je starší verze dokumentu!

Vytvořeno: 14.6.2026 | Aktualizováno: 14.06.2026 08:54

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 README dokumentace projektu. Lokální otestování s vlastním Google účtem zde zatím není zaznamenané.

gws poskytuje jedno CLI pro větší část ekosystému Google Workspace. Místo ručního psaní REST volání načítá za běhu 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.

Doporučená instalace je stažení předpřipraveného binárního balíčku z GitHub Releases. Alternativně lze použít npm balíček, který stáhne odpovídající binárku, build z Rust zdrojů, Nix nebo Homebrew.

npm install -g @googleworkspace/cli

cargo install --git https://github.com/googleworkspace/cli --locked

nix run github:googleworkspace/cli

brew install googleworkspace-cli

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.

Nejjednodušší lokální workflow je:

gws auth setup
gws auth login
gws drive files list --params '{"pageSize": 5}'

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:

gws auth login -s drive,gmail,sheets

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í:

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

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

gws drive files list --params '{"pageSize": 10}'

Vytvoření Google Sheets dokumentu:

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

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

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

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

gws schema drive.files.list

Stránkovaný výstup jako NDJSON:

gws drive files list --params '{"pageSize": 100}' --page-all

Repozitář obsahuje 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:

npx skills add https://github.com/googleworkspace/cli

Instalace jen vybraných skills:

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

Projekt obsahuje také Gemini CLI extension konfiguraci. Typický postup podle dokumentace:

gws auth setup
gemini extensions install https://github.com/googleworkspace/cli

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

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:

gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"

gws calendar +agenda

gws workflow +standup-report

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í.
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 Google Cloud Model Armor pro sanitizaci promptů nebo odpovědí v agentních scénářích.

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.