Gws

Google Workspace CLI (gws)

A CLI tool built in Rust that wraps every Google Workspace API into composable commands with structured JSON output. It dynamically builds its command structure from Google's Discovery Service, so it always supports the latest APIs without updates.

Prerequisites

• gcloud CLI: Required for authentication. Install via brew install --cask google-cloud-sdk on macOS.
• Node.js/npm: Required to install gws.

Installation & Setup

# 1. Install the CLI
npm install -g @googleworkspace/cli

# 2. Set up auth (interactive walkthrough for GCP project + OAuth)
gws auth setup

# 3. Login to Google Workspace account
gws auth login

The gws auth setup command walks through: 1. GCP project creation or selection (all via CLI) 2. Enabling required Google Workspace APIs 3. OAuth client configuration

Multiple accounts (work, personal) can be added. For agent-dedicated accounts, grant Full Access (all OAuth scopes). For personal/work accounts, start with Limited Access.

Core Usage Patterns

Command Structure

# Standard API call
gws <service> <resource> <method> --params '{"key": "value"}' --json '{"body": "data"}'

# Helper shortcut (handles encoding/formatting)
gws <service> +<helper> --flag value

Key Services & Helpers

All responses return structured JSON for reliable agent parsing.

Gmail

# Search inbox
gws gmail users messages list --params '{"userId": "me", "q": "is:unread"}'

# Read a message
gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID"}'

# Send email (helper handles RFC 2822 encoding)
gws gmail +send --to alice@company.com --subject 'Report Ready' \
  --body 'The Q2 report is ready for review.'

# Triage unread
gws gmail +triage --max 5 --query 'from:boss'

Calendar

# Today's agenda
gws calendar +agenda

# Create event
gws calendar +insert --summary 'Standup' \
  --start '2026-03-10T09:00:00-07:00' \
  --end '2026-03-10T09:30:00-07:00'

# Create recurring event with attendees
gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Weekly Standup",
    "start": {"dateTime": "2026-03-10T09:00:00", "timeZone": "America/Vancouver"},
    "end": {"dateTime": "2026-03-10T09:30:00", "timeZone": "America/Vancouver"},
    "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO"],
    "attendees": [{"email": "team@company.com"}]
  }'

Drive

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

# Upload file
gws drive +upload --file ./report.pdf --parent FOLDER_ID

# Create folder
gws drive files create --json '{"name": "Q2 Project", "mimeType": "application/vnd.google-apps.folder"}'

# Download / Export
gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' -o report.pdf
gws drive files export --params '{"fileId": "FILE_ID", "mimeType": "application/pdf"}' -o doc.pdf

# Share with someone
gws drive permissions create --params '{"fileId": "FOLDER_ID"}' \
  --json '{"role": "writer", "type": "user", "emailAddress": "colleague@company.com"}'

Sheets

# Read range
gws sheets +read --spreadsheet-id SHEET_ID --range 'Contacts!A2:C'

# Append row
gws sheets +append --spreadsheet-id SHEET_ID --range 'Sheet1' \
  --values '["2026-03-05", "Marketing", "Ad spend", "1500"]'

Docs, Chat, Meet, Forms

# Create document
gws docs documents create --json '{"title": "Meeting Notes"}'

# Write to doc
gws docs +write --document-id DOC_ID \
  --text '## Project: Q2 Launch\n\n### Objective\nLaunch by end of Q2.'

# Send chat message
gws chat +send --space spaces/TEAM_SPACE --text 'Check updated policy.'

# Create Meet room
gws meet spaces create --json '{"config": {"accessType": "OPEN"}}'

# Create form
gws forms forms create --json '{"info": {"title": "Feedback", "documentTitle": "Feedback Form"}}'

MCP Server Integration

For deeper Claude Code integration, gws provides a built-in MCP server:

# Start MCP server with specific services
gws mcp -s drive,gmail,calendar

Configure in .mcp.json or Claude Desktop settings:

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

Each service adds ~10-80 tools. Keep the service list focused to stay under tool limits.

Agent Skills from the Repo

The gws repo ships 100+ SKILL.md files (service skills, persona bundles, helpers, recipes). See references/services.md for the full catalog and persona details.

# Clone and symlink all skills
git clone https://github.com/googleworkspace/cli.git
ln -s $(pwd)/cli/skills/gws-* ~/.claude/skills/

# Or copy specific ones
cp -r cli/skills/gws-drive cli/skills/gws-gmail ~/.claude/skills/

Model Armor (Safety)

Sanitize API responses to prevent prompt injection from email/doc content:

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

Modes: warn (flags suspicious content) or block (strips it out).

Additional Resources

Reference Files

• `references/services.md` - Complete service list with all helpers and API patterns
• `references/setup-troubleshooting.md` - Common setup issues and OAuth configuration details

Scripts

• `scripts/check-gws.sh` - Verify gws installation and auth status

GWS Service Reference

Complete Service List

Core Productivity

Communication & Collaboration

Administration

Other Services

Persona Skills (Pre-Built Agent Roles)

Common Patterns

Listing with Pagination

# First page
gws drive files list --params '{"pageSize": 100}'

# Next page (use nextPageToken from response)
gws drive files list --params '{"pageSize": 100, "pageToken": "TOKEN"}'

Filtering and Searching

# Gmail search operators
gws gmail users messages list --params '{"userId": "me", "q": "from:boss subject:urgent after:2026/03/01"}'

# Drive search
gws drive files list --params '{"q": "name contains '\''report'\'' and mimeType='\''application/pdf'\''"}'

# Calendar time range
gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-01T00:00:00Z", "timeMax": "2026-03-31T23:59:59Z"}'

Batch Operations

# Sheets batch update
gws sheets spreadsheets batchUpdate --params '{"spreadsheetId": "ID"}' \
  --json '{"requests": [{"updateCells": {...}}, {"addSheet": {...}}]}'

# Docs batch update
gws docs documents batchUpdate --params '{"documentId": "ID"}' \
  --json '{"requests": [{"insertText": {"location": {"index": 1}, "text": "Hello"}}]}'

Error Handling

Common error codes:

• 401: Auth expired - run gws auth login again
• 403: Insufficient permissions - check OAuth scopes in gws auth setup
• 404: Resource not found - verify ID
• 429: Rate limited - wait and retry

Output Formatting

# Default: JSON output
gws drive files list --params '{"pageSize": 5}'

# Pipe to jq for processing
gws drive files list --params '{"pageSize": 5}' | jq '.files[].name'

# Save output to file
gws drive files list --params '{"pageSize": 5}' -o files.json

GWS Setup & Troubleshooting

Prerequisites

gcloud CLI

Required for OAuth authentication with Google Cloud.

# macOS
brew install --cask google-cloud-sdk

# Verify
gcloud --version

Node.js / npm

# Check version
node --version  # v18+ recommended
npm --version

Setup Walkthrough

Step 1: Install gws

npm install -g @googleworkspace/cli
gws --version

Step 2: Auth Setup

gws auth setup

This interactive command handles:

1. GCP Project: Create new or select existing project 2. API Enablement: Select which Google Workspace APIs to enable

• Start with: Gmail, Calendar, Drive, Sheets, Docs
• Add more later as needed

3. OAuth Client: Configure OAuth 2.0 credentials

• May require manual OAuth client creation in GCP Console
• Copy Client ID and Client Secret when prompted

Step 3: Login

gws auth login

Choose access level:

• Full Access: For dedicated agent accounts (YOLO mode)
• Limited Access: For personal/work accounts (recommended to start)

Step 4: Verify

# Test with a simple query
gws gmail users messages list --params '{"userId": "me", "maxResults": 1}'

Common Issues

"gws: command not found"

# Check if npm global bin is in PATH
npm config get prefix
# Add to PATH if needed: export PATH="$(npm config get prefix)/bin:$PATH"

# Or use npx
npx @googleworkspace/cli --version

OAuth Consent Screen Issues

If the consent screen shows "unverified app": 1. This is normal for personal/development use 2. Click "Advanced" > "Go to [app name]" to proceed 3. For production, submit app for Google verification

"Access Not Configured" (403)

API not enabled for the GCP project:

# Re-run setup to enable additional APIs
gws auth setup
# Select the APIs that need enabling

Token Expired (401)

# Re-authenticate
gws auth login

Rate Limiting (429)

Google Workspace APIs have per-user and per-project quotas:

• Gmail: 250 quota units/second/user
• Drive: 12,000 requests/minute
• Calendar: 500 requests/100 seconds/user

Wait and retry, or implement exponential backoff in scripts.

Multiple Accounts

# Add another account
gws auth login
# Select different account or add new one

# List configured accounts
gws auth list

# Switch active account
gws auth switch

MCP Server Won't Start

# Verify gws is accessible
which gws

# Test MCP server manually
gws mcp -s gmail

# Check service names are valid
gws mcp -s drive,gmail,calendar  # comma-separated, no spaces

Proxy / Corporate Network

If behind a proxy:

# Set proxy environment variables
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

Security Best Practices

1. Principle of least privilege: Start with Limited Access, expand as needed 2. Dedicated agent account: Use a separate Google account for automated agents 3. Review OAuth scopes: Only enable APIs actually needed 4. Model Armor: Enable sanitization for content from untrusted sources 5. Audit logs: Monitor agent activity through Google Workspace admin console 6. Token storage: gws stores tokens locally - protect the machine accordingly