gws: The Single Command-Line Tool That Covers All of Google Workspace – and Talks to AI Agents

Key Takeaway: The Google Workspace CLI (gws) replaces every scattered REST call, half-finished wrapper library, and manual browser click with one unified command-line tool — dynamically built from Google’s own Discovery Service — that works equally well for human automation and AI agent workflows through a built-in MCP server and 100-plus pre-packaged agent skills.

Most developers who work with Google Workspace have lived through the same frustration: three different API clients for Drive, Gmail, and Calendar; documentation that describes HTTP endpoints but not how to compose them sensibly from the shell; and authentication flows that require writing boilerplate OAuth code before a single file can be listed. The Google Workspace CLI, published under the handle gws at github.com/googleworkspace/cli, is a direct answer to that frustration. It is one binary, one authentication flow, and one consistent output format for the entire Workspace surface area — including the AI agent layer that is increasingly doing the work that humans used to do manually.

Note that while the project lives under the googleworkspace GitHub organization, it is not an officially supported Google product.

What Is the Google Workspace CLI?

gws is a command-line interface built to cover Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and every other Google Workspace API from a single executable. Every response it produces is structured JSON, which means output pipes cleanly into jq, into shell scripts, and directly into the context window of an LLM. There is no custom output format to parse, no human-readable prose to strip, and no per-service client library to install alongside it.

The project is written in Rust for native performance and distributed both as an npm package with pre-built binaries and as source available through cargo. The architecture is built around a two-phase command parser: it reads the first argument to identify the target service, fetches that service’s Discovery Document from Google (cached for 24 hours), builds the full command tree from the document’s resource and method definitions, and only then re-parses the remaining arguments. Every --help response, every flag, and every sub-command is derived directly from Google’s own API specification at runtime.

Why Dynamic Discovery Changes Everything

The single most important architectural decision in gws is that its command surface is not static. It does not ship a hardcoded list of commands that someone has to maintain in step with Google’s API releases. Instead, it reads Google’s Discovery Service at runtime and constructs its entire interface from whatever Google publishes there. When Google adds a new API method, endpoint, or parameter, gws picks it up automatically on the next invocation without requiring a package update. This means the CLI is perpetually current with the actual API surface, not with whatever version of it a maintainer last encoded by hand.

The practical consequence for developers is that gws schema <method> can introspect any method’s full request and response schema at any time, and --help on any resource always reflects the live API definition. For AI agents, it means the tool can reason about and call any Workspace method without needing a specialized integration for each one.

Installation

Via npm (Recommended for Most Users)

Node.js 18 or higher is the only prerequisite. Install the CLI globally with a single command:

npm install -g @googleworkspace/cli

The npm package bundles pre-built native binaries for your operating system and architecture. No Rust toolchain is required.

Pre-Built Binaries and Building from Source

Pre-built binaries for Windows, macOS, and Linux are available on the GitHub Releases page for environments where npm is unavailable or undesirable.

Developers who want to build from source with a Rust toolchain can use:

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

A Nix flake is also provided for Nix-based environments:

nix run github:googleworkspace/cli

Authentication Setup

gws supports multiple authentication strategies to cover local development, CI pipelines, server deployments, and agent-automated flows.

Interactive Setup (Recommended Starting Point)

The fastest path for local use requires the gcloud CLI and a Google Cloud project. If neither exists yet, the following single command handles project creation, API enablement, OAuth client setup, and initial login in one guided session:

gws auth setup
gws auth login

Credentials are encrypted at rest using AES-256-GCM and stored in your OS keyring under ~/.config/gws/. Subsequent logins for new scopes or accounts use gws auth login alone.

One important scope-limit to be aware of: if your OAuth app is in testing mode (the default for new projects), Google caps the consent screen at approximately 25 OAuth scopes. Attempting the full recommended scope preset — which includes 85-plus scopes — will fail for unverified apps. Restrict the login to the services you actually need:

gws auth login -s drive,gmail,calendar

Multiple accounts are fully supported. Register each one separately and switch between them as needed:

gws auth login --account [email protected]
gws auth login --account [email protected]
gws auth default [email protected]
gws --account [email protected] drive files list  # one-off override

CI and Headless Environments

For pipelines and servers without a browser, complete the interactive OAuth flow once on a local machine, export the resulting credentials, and transfer them to the target environment:

# On the local machine
gws auth export --unmasked > credentials.json

# On the CI/headless machine
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list

Service Accounts and Domain-Wide Delegation

Point the credentials variable at a service account key file for server-to-server authentication without any interactive login step. For Google Workspace domains requiring impersonation across user accounts, add the delegation target:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
export [email protected]
gws drive files list

Core Commands in Practice

Once authenticated, the command structure follows a consistent pattern: gws <service> <resource> <method> [flags]. Every method accepts --params for URL and query parameters as a JSON string and --json for the request body.

Working with Drive

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

# Upload a file
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

# Preview a request without executing it
gws drive files list --params '{"pageSize": 5}' --dry-run

Gmail and Calendar

# List recent inbox messages
gws gmail users messages list --params '{"userId": "me", "maxResults": 5}'

# List upcoming calendar events
gws calendar events list \
  --params '{"calendarId": "primary", "maxResults": 10, "orderBy": "startTime", "singleEvents": true}'

Sheets and Docs

Sheets range notation uses the ! character, which Bash interprets as history expansion. Always wrap range values in single quotes:

# Read a cell range
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

# Append rows
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

# Create a new spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

Chat

# Send a message to a Chat space
gws chat spaces messages create \
  --params '{"parent": "spaces/SPACE_ID"}' \
  --json '{"text": "Deployment complete."}'

AI Agent Skills and the MCP Server

gws was designed from the start for agent consumption, not just human use. It ships with more than 100 SKILL.md files covering every supported API, plus higher-level workflow helpers and 50 curated recipes for Gmail, Drive, Docs, Calendar, and Sheets.

Installing Agent Skills

Skills follow the standard npx skills pattern and can be installed wholesale or selectively:

# Install all skills at once
npx skills add https://github.com/googleworkspace/cli

# Install only what you need
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

For Gemini CLI users, the extension route is even simpler. After running gws auth setup once, install the extension into the Gemini CLI agent directly:

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

This gives the Gemini CLI agent direct access to all gws commands and skills. Because gws manages its own credential storage, the extension inherits authentication automatically — no additional token plumbing is needed.

Running the MCP Server

gws mcp starts a Model Context Protocol server over stdio, exposing Google Workspace APIs as structured tools that any MCP-compatible client — Claude Desktop, Gemini CLI, VS Code, Cursor, and others — can call directly:

gws mcp -s drive,gmail,calendar

Configure it in any MCP client’s settings file:

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

Each additional service exposes roughly 10 to 80 tools depending on the API’s method count. Keep the service list scoped to what the agent actually needs to stay within your MCP client’s tool limit, which is typically between 50 and 100 tools.

Advanced Features

Automatic Pagination

Large result sets across any Workspace API can be consumed without manually tracking page tokens:

# Stream all files as newline-delimited JSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

The --page-limit flag caps the number of pages fetched and --page-delay adds a millisecond delay between requests for rate-limit-sensitive operations.

Model Armor — Response Sanitization for Agents

When gws is used inside an agentic pipeline, API responses can carry content that triggers prompt injection against the LLM consuming them. The --sanitize flag integrates with Google Cloud Model Armor to scan responses before they reach the agent:

gws gmail users messages get \
  --params '{"userId": "me", "id": "MESSAGE_ID"}' \
  --sanitize "projects/PROJECT/locations/LOCATION/templates/TEMPLATE"

Set GOOGLE_WORKSPACE_CLI_SANITIZE_MODE=block to reject flagged responses entirely rather than just warning.

Who Should Use the Google Workspace CLI?

gws is a direct fit for several categories of users. Developers automating Workspace tasks from shell scripts or CI pipelines gain a consistent, well-typed interface without maintaining separate API clients per service. Teams building AI agents that need to read emails, update spreadsheets, schedule meetings, or search Drive will find the MCP server and agent skills remove most of the integration work. Platform engineers managing Google Workspace tenants can combine the Admin API coverage with service account authentication and domain-wide delegation for organization-wide automation.

The project is under active development heading toward v1.0, so teams should anticipate breaking changes between minor versions. That caveat aside, the combination of dynamic API coverage, zero-boilerplate structured output, multi-account credential management, and a first-class MCP server makes it the most complete open-source option for treating Google Workspace as a programmable system.

Conclusion

The Google Workspace surface area has always been rich enough to power complex automations but awkward enough to discourage building them. gws resolves both problems at once: it presents the entire API as a single coherent CLI, stays perpetually current through Discovery Service introspection, and adds an agent layer that makes it immediately useful in LLM workflows without any custom glue code. For developers who spend time in terminals and developers who build systems where AI agents do the work, it is worth installing and exploring today.

Repository: https://github.com/googleworkspace/cli
npm Package: https://www.npmjs.com/package/@googleworkspace/cli
Skills Index: https://github.com/googleworkspace/cli/blob/main/docs/skills.md