Google Workspace CLI

Overview

Google Workspace CLI (gws) is an open-source command-line tool that gives developers, AI agents, and automation pipelines unified programmatic access to every Google Workspace API through a single binary. Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin SDK are all reachable from one consistent interface, with no custom authentication boilerplate, no pagination wiring, and no per-service wrapper maintenance.

Built by Justin Poehnelt, a Senior Developer Relations Engineer at Google, and hosted under the official googleworkspace GitHub organization, gws was designed from the ground up for machine consumption — not human discoverability. Its most technically distinctive feature is dynamic command generation: rather than shipping a static list of commands, gws reads Google's Discovery Service at runtime and automatically builds its entire command surface. When Google adds a new API endpoint, gws picks it up immediately without requiring a CLI update.

With over 20.8k GitHub stars and active development toward v1.0 (currently at v0.16.0), gws has become a reference-level tool for teams building AI workflow automation on top of Google's ecosystem.

Key Features

• Discovery-Driven Dynamic API Surface — Commands are generated at runtime from Google's Discovery Service, not hand-maintained. New Workspace API endpoints appear as callable commands automatically, and Discovery Documents are cached for 24 hours. Schema introspection via gws schema drive.files.list --resolve-refs exposes full method signatures, parameter types, and required OAuth scopes as machine-readable JSON — a cleaner alternative to embedding static documentation in system prompts.

• Agent-First Design — The tool ships with 100+ structured SKILL.md files with YAML frontmatter — one per API surface plus higher-level workflow recipes. Skills encode agent guidance not visible in --help: always use --dry-run for mutating operations, always confirm before write/delete commands. Structured JSON is the default output format, making every response directly parseable by any LLM without transformation.

• Gemini CLI Extension — After authenticating with gws auth setup, install the extension with gemini extensions install https://github.com/googleworkspace/cli. This integrates gws with the Model Context Protocol (MCP) Gemini CLI ecosystem, enabling conversational access to Drive, Gmail, Calendar, and all Workspace APIs using your existing credentials.

• Prompt Injection Defense — The --sanitize flag pipes API responses through Google Cloud Model Armor before returning them to the caller. This defends against indirect prompt injection embedded in Workspace content (a malicious email body instructing the agent to forward messages, for example). Additional input hardening covers resource-name validation, path-traversal protections on selected helper surfaces, and path-parameter encoding to prevent common agent hallucination patterns.

• Unified Multi-Service Coverage — Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and every other Workspace API respond to the same gws <service> <resource> <method> [flags] pattern. Helper commands prefix with + for common shortcuts: gws gmail +send, gws drive +upload, gws sheets +append. All commands support --format output in JSON, table, YAML, or CSV.

• Headless & CI/CD Support — For headless environments and CI/CD pipelines, credentials can be exported from an interactive session and consumed via GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE, or a pre-obtained OAuth token supplied through GOOGLE_WORKSPACE_CLI_TOKEN. Credentials are encrypted at rest with AES-256-GCM.

How to Get Started

Prerequisites

• Node.js (any recent LTS version) for the npm install path
• gcloud CLI installed and authenticated (gcloud auth login) if you want the automated OAuth setup

Automated Setup (Recommended)

# Install globally via npm
npm install -g @googleworkspace/cli

# Run the interactive setup wizard
gws auth setup

gws auth setup walks you through Google Cloud project configuration, enabling the necessary Workspace APIs, and completing OAuth login. Credentials are encrypted at rest with AES-256-GCM.

Verify the installation:

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

Manual OAuth Setup

If gws auth setup cannot automate project creation due to organization restrictions:

1. Create a GCP project and navigate to APIs & Services → OAuth consent screen (set type to External; add your email as a test user)
2. Go to Credentials → Create Credentials → OAuth client ID — choose Desktop app (not Web application)
3. Download the JSON file, move it to ~/.config/gws/client_secret.json
4. Run gws auth login and complete the browser OAuth consent flow

Common gotcha: Unverified OAuth apps in testing mode are limited to ~25 OAuth scopes. The "all services" preset uses 85+ scopes and will fail. Authorize only the services you need and add more later with gws auth login.

Gemini CLI Extension

After installing and authenticating gws, add it as a Gemini CLI extension:

gemini extensions install https://github.com/googleworkspace/cli

This enables conversational Workspace access through the Gemini CLI using your existing gws credentials.

Install Agent Skills

# 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-gmail

Community & Ecosystem

gws is written in Rust and distributed as pre-built native binaries via npm (@googleworkspace/cli), Homebrew, and a Nix flake (nix run github:googleworkspace/cli). The project is under active development, and the latest GitHub release is v0.16.0 as of March 13, 2026. The README still warns that breaking changes are expected before v1.0.

The repository had about 20.8k GitHub stars and roughly 965 forks as of mid-March 2026, reflecting strong early developer interest driven by a Hacker News front-page appearance. The author's companion post, "You Need to Rewrite Your CLI for AI Agents," laid out seven design principles for agent-to-agent compatible CLI tools and generated significant discussion among AI infrastructure engineers.

The documented ecosystem currently centers on agent skills, Gemini CLI extension installation, and standard CI/headless credential flows. Contributors work under the googleworkspace GitHub organization; the project carries the standard "not an officially supported Google product" disclaimer.

Pricing & Plans

Google Workspace CLI is fully open source and free to use. There are no paid tiers, usage limits, or premium features.

You need a Google account and a GCP project for OAuth credentials. All Google Workspace API usage is subject to standard Google API quotas (free tier applies).

Best For

• Backend developers and data engineers automating Workspace operations in CI/CD pipelines without REST boilerplate
• AI agent builders who need programmatic access to Gmail, Drive, Calendar, and Sheets via agent skills and Gemini CLI extension
• Platform teams replacing Google Apps Script with a CLI tool that supports package managers, standard auth, and full CI/CD integration
• Security-conscious developers who want prompt injection defense built into their Workspace automation layer
• Open source projects and indie developers who need free, zero-cost programmatic Workspace access

FAQ