gcloud covers everything in the GCP ecosystem except Google Workspace. The gws CLI fills that gap — and it was designed from day one for AI agents, not human-interactive use. This hub collects the notes on the tool, its design philosophy, the OAuth friction points, and the broader question of when to use CLIs versus MCP.
The Tool
Google Workspace CLI (gws) covers what gws is, why it exists, and how it works. The key architectural point: gws reads Google’s Discovery Service at runtime and generates commands dynamically from current API specs, so it stays current with API changes automatically. It also ships with a built-in MCP server and 100+ agent skill files.
The Design Philosophy
Agent-First CLI Design Principles breaks down the seven principles behind gws from Justin Poehnelt’s “You Need to Rewrite Your CLI for AI Agents.” The core shift: human CLIs optimize for discoverability, agent CLIs optimize for predictability and input validation. The principles — raw JSON payloads, schema introspection, context window discipline, input hardening against hallucinations, shipping skill files, multi-surface delivery, and safety rails — apply to any tool targeting agent consumers.
Getting Set Up
Google OAuth CLI Setup Gotchas documents the three traps that cause most OAuth setup failures: choosing Web application instead of Desktop app as the OAuth client type, missing the test user configuration step, and hitting the 25-scope limit on unverified apps. It also covers multi-account management and headless/CI credential patterns.
CLI vs MCP
CLI vs MCP for AI Agents examines the practical tradeoffs with benchmark data. The short version: CLI wins on token efficiency and composability; MCP wins on typed validation and client universality. gws offers both surfaces from a single binary, which is increasingly the right answer.
Sheets as Data Source
Google Sheets as Analytics Data Source covers the shadow data problem — Sheets are a persistent part of GCP analytics stacks whether you want them to be or not — and how gws makes Sheets automation tractable for AI agents. Includes the BigQuery external table pattern and the convergence of data and productivity tooling through AI agent layers.