gws — Google Workspace CLI

Official Google-published CLI for all Workspace APIs. Dynamically built from Google Discovery Service — covers every API endpoint automatically as Google adds them.

Note: This is the official Google-org CLI (googleworkspace/cli), distinct from third-party alternatives. Prefer gws for new integrations — it has native MCP mode and active development from Google.

APIs Covered

• Drive — files, folders, sharing, permissions
• Gmail — messages, labels, drafts, send
• Calendar — events, calendars, invites
• Sheets — spreadsheets, values, formatting
• Docs — documents read/write
• Chat — spaces, messages
• Admin — users, groups, org units
• Tasks — task lists, tasks
• Meet — meeting resources
• ...and every other Workspace API via Discovery Service

Installation

npm install -g @googleworkspace/cli
# or: cargo install --git https://github.com/googleworkspace/cli --locked
# or: nix run github:googleworkspace/cli

Verify:

gws --version

Authentication (One-time Setup Required)

⚠️ Auth requires manual action — OAuth credentials must be set up once per account.

Option A: With gcloud (fastest)

gws auth setup   # creates GCP project, enables APIs, logs in
gws auth login   # subsequent logins / scope changes

Option B: Without gcloud (manual GCP console)

1. Go to console.cloud.google.com → create project
2. Enable Workspace APIs (Drive, Gmail, Calendar, etc.)
3. Create OAuth 2.0 Client ID (Desktop app type)
4. Download credentials JSON
5. Set: export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
6. Run: gws auth login

Option C: Service Account (server/headless)

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json

Credentials are encrypted at rest (AES-256-GCM) with OS keyring.

Basic Usage

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

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

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

# Send a Gmail message
gws gmail users messages send --params '{"userId": "me"}' --json '{"raw": "<base64>"}'

# Inspect any method schema
gws schema drive.files.list

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

# Dry-run (preview request without executing)
gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "test"}' --dry-run

MCP Server Mode (AI Agent Use)

gws can act as an MCP server, exposing all Workspace APIs as structured tools for Claude, Cursor, VS Code, etc.

# Start MCP server (all services)
gws mcp

# Start MCP server (specific services only — recommended)
gws mcp -s drive,gmail,calendar

# Compact mode — reduces from 200-400 tools to ~26 meta-tools (saves context)
gws mcp -s drive,gmail,calendar --tool-mode compact

Add to your agent config (e.g. OpenClaw / mcporter):

{
  "mcpServers": {
    "google-workspace": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar,sheets,docs", "--tool-mode", "compact"]
    }
  }
}

OpenClaw Agent Usage

After auth setup, the agent can:

• Read/send Gmail → automate email workflows
• Read/write Calendar → schedule meetings, parse availability
• Read/write Sheets → log data, pull reports
• Manage Drive → organize files, share docs
• Chat → send notifications to Google Chat spaces

Example — list recent emails:

gws gmail users messages list --params '{"userId": "me", "maxResults": 10, "q": "is:unread"}'

Notes

• Auth is manual (one-time) — must complete gws auth setup before first use
• Active development — pre-v1.0, expect breaking changes; check GitHub for latest
• Official Google org — published by googleworkspace on GitHub, not a third-party
• No boilerplate — structured JSON output, works with jq and scripts
• MCP-native — expose any Workspace API as an MCP tool with a single command

Status

• Viability: ✅ HIGH — official Google org, MCP-native, npm installable
• Auth blocker: ⚠️ Manual one-time gws auth setup required (GCP project needed)
• Replacement: Better long-term choice vs. gcloud scripting — auto-updates with Google API surface