05.03.2026

GWS CLI: Automate Google Workspace from Your Terminal

head-image

Managing Google Workspace programmatically has always meant wrestling with REST APIs, OAuth flows, and scattered documentation. The new Google Workspace CLI (gws) changes that. One tool handles Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more.

What is GWS CLI?

GWS is a command-line interface that dynamically generates commands from Google's Discovery Service. When Google adds a new API endpoint, gws picks it up automatically. No SDK updates required.

The tool outputs structured JSON, making it ideal for scripting, pipelines, and AI agent integrations. It supports multiple authentication methods including OAuth, service accounts, and domain-wide delegation.

Key Features

Dynamic API coverage: Commands are built at runtime from Google's Discovery Service
Structured JSON output: Perfect for piping to jq or feeding into automation
Multiple auth flows: OAuth for local dev, service accounts for CI/CD, token passthrough from gcloud
Built-in MCP server: Expose Workspace APIs as tools for Claude, Gemini, or any MCP client
Auto-pagination: Stream large result sets with --page-all
AI agent skills: Ships with 100+ ready-to-use skill files

Installation

npm install -g @googleworkspace/cli

Pre-built binaries are also available on GitHub Releases for those who prefer not to use npm.

Quick Start

# One-time setup (creates GCP project, enables APIs)
gws auth setup

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

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

# Send a Chat message (dry-run first)
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

Using in CI/CD

For headless environments, export credentials from an authenticated machine:

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

# In CI pipeline
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list

Service accounts work without any login step:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws gmail users messages list --params '{"userId": "me"}'

AI Agent Integration

The MCP server mode lets AI agents interact with Workspace directly:

gws mcp -s drive,gmail,calendar

Configure it in your MCP client (Claude Desktop, VS Code, etc.) to give agents access to list files, send emails, or manage calendar events through natural language.

Conclusion

GWS CLI brings Google Workspace automation to the command line where DevOps workflows live. Structured output, flexible auth, and AI-ready integrations make it a strong addition to any SRE toolkit.

Akmatori helps SRE teams automate incident response and infrastructure management with AI agents. Learn more or deploy on Gcore Cloud for a managed experience.

Akmatori team