ServicesAboutNotesContact Get in touch →
EN FR
Note

Google Workspace CLI (gws)

The gws CLI gives programmatic access to every Google Workspace API through a single binary — Gmail, Drive, Calendar, Sheets, Docs — filling the gap gcloud has never covered.

Planted
gcpmcpautomationaidata engineering

The gcloud CLI covers GCP infrastructure (Compute, BigQuery, Cloud Storage, IAM, and more) but does not cover Google Workspace. Gmail, Google Sheets, Calendar, and Drive are not accessible via gcloud. The Google Workspace CLI (gws) fills that gap.

What gws Is

gws is an open-source command-line tool created by Justin Poehnelt, a Senior Developer Relations Engineer at Google’s Workspace team. It gives programmatic access to every Google Workspace API through a single binary: Gmail, Drive, Calendar, Sheets, Docs, Chat, Admin, and more. The project lives under the official googleworkspace GitHub organization and carries the standard “not an officially supported Google product” disclaimer.

As of early 2026, the project is at v0.3.5 with roughly 5,100 GitHub stars. It’s written in Rust, distributed via npm with pre-built binaries, and under active development toward v1.0 with breaking changes expected. The pre-v1.0 status and unofficial support designation are real maturity risks — worth tracking closely, but not reasons to wait.

Terminal window
# Install globally via npm (pre-built native binaries, no Rust required)
npm install -g @googleworkspace/cli


# Verify with a quick list of recent Drive files
gws drive files list --params '{"pageSize": 5}'

What Came Before

Before gws, the main automation option for Google Workspace was Google Apps Script. It works, but it’s fundamentally inadequate for data engineering contexts:

  • 6-minute execution timeout on free accounts (30 minutes on Workspace)
  • Single-threaded synchronous execution — no parallelism
  • No package manager — limited to built-in services
  • Daily API quota caps that are easy to hit in pipeline contexts
  • No CI/CD integration — everything lives inside Google’s runtime

The REST APIs work too, but require substantial boilerplate for authentication, pagination, and error handling — three things engineers should not be writing from scratch in 2026.

gws abstracts all of this behind a consistent interface.

The Dynamic Discovery Architecture

What’s technically interesting about gws is how it builds its command surface. Rather than shipping a static list of commands baked at release time, gws reads Google’s Discovery Service at runtime and dynamically generates every command from the current API specifications.

When Google adds a new endpoint, the CLI picks it up automatically. Discovery documents are cached for 24 hours, so there’s a minimal performance cost. This means the tool will never fall behind the APIs it wraps — a genuine architectural advantage over hand-written wrappers.

You can inspect the schema for any method directly:

Terminal window
# Get full parameter and response schema for Drive file listing
gws schema drive.files.list

This returns machine-readable JSON: parameters, request body, response types, OAuth scopes. Useful both for humans figuring out what flags to pass and for agents generating API calls without needing to consult external documentation.

Agent-First Design

The most interesting thing about gws for data engineers is not its API coverage — it’s the design philosophy behind it. The tool was built from day one for AI agent consumption, not human interactive use. It ships with:

  • 100+ agent skill files — structured Markdown files with YAML frontmatter encoding guidance beyond what --help shows (“Always use --dry-run for mutating operations,” “Always confirm with user before executing write/delete commands”)
  • A built-in MCP server — gws mcp -s drive,gmail,calendar exposes Workspace APIs as structured tools over stdio for any MCP-compatible client
  • Structured JSON output by default — no human-readable formatting that agents have to parse around
  • Input hardening against hallucinations — validation against directory traversal, control characters, query parameter injection, and double-encoding

The seven principles behind this design are documented separately. The core distinction: human CLIs optimize for discoverability; agent CLIs optimize for predictability and input validation.

MCP and Direct Shell: Two Integration Paths

gws integrates with AI coding agents via two complementary paths.

MCP server mode exposes Workspace APIs as structured tools for any MCP-compatible client:

Terminal window
# Register gws as an MCP server in Claude Code
claude mcp add gws -- gws mcp -s drive,gmail,calendar

Or by editing ~/.claude.json directly:

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar"]
    }
  }
}

Each service adds roughly 10-80 tools, so scope to what you actually need to stay under typical client tool limits of 50-100 tools. Verify the connection with /mcp in a Claude Code session — you should see gws: connected.

Direct shell execution lets Claude Code invoke gws commands directly, parse the JSON output, and chain operations together. This path is often more token-efficient than MCP because tools only consume tokens when actively used, rather than loading schema definitions into context permanently. See CLI vs MCP for AI Agents for the full tradeoff analysis.

Installing Agent Skills

The repo ships 100+ structured skill files that can be loaded into any agent that uses skill files:

Terminal window
# Install all skills
npx skills add https://github.com/googleworkspace/cli


# Or pick specific services
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

Skills encode the operational wisdom that isn’t obvious from API docs: which operations are reversible, when to confirm before proceeding, how to handle pagination for large result sets.

Third-Party Alternatives

Several community MCP servers exist for Google Workspace. The most feature-complete is taylorwilsdon’s google_workspace_mcp, covering 12 services with 100+ tools. Implementations also exist in Go and Python. They all require similar OAuth setup and offer comparable capabilities.

The gws CLI’s advantage over these is maintenance provenance: it lives under the official Google Workspace GitHub org, is authored by a Google DevRel engineer, and stays current with API changes dynamically rather than requiring manual updates. The disadvantage is its pre-v1.0 maturity and unofficial support status.

For Sheets-specific workflows in data engineering contexts, gws is currently the most capable option with the best agent integration story.