anton-abyzov/gws

Google Workspace CLI (gws)

One CLI for all of Google Workspace — Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and every API published via Google Discovery Service. Built in Rust, distributed via npm, designed for humans and AI agents.

Upstream: googleworkspace/cli (Apache 2.0) Status: Pre-v1.0 — breaking changes possible. Pin versions in production scripts.

---

When to Use gws vs Native Claude MCP

| Need | Use | |------|-----| | Read/send Gmail | Native claude_ai_Gmail (already configured) | | Calendar events | Native claude_ai_Google_Calendar (already configured) | | Google Drive files | gws (no native integration) | | Google Sheets | gws (no native integration) | | Google Docs | gws (no native integration) | | Google Chat | gws (no native integration) | | Admin / Directory | gws (no native integration) | | Bulk automation across services | gws (unified CLI, scriptable) | | Custom/new Google APIs | gws (dynamic discovery picks up new APIs automatically) |

---

Installation

# Via npm (recommended — includes pre-built native binary)
npm install -g @googleworkspace/cli

# Verify
gws --version

Alternative: download pre-built binaries from GitHub Releases.

---

Authentication Setup

Prerequisites

1. A Google Cloud project (create via console.cloud.google.com or gcloud)
2. Required Google APIs enabled in the project (Drive API, Gmail API, etc.)
3. OAuth consent screen configured (add test users if in testing mode)

Interactive Setup (Recommended)

# Guided setup — walks through GCP project configuration
gws auth setup

# OAuth login — opens browser for consent
gws auth login

# Verify authentication
gws auth status

Service Account (Headless/CI)

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

Pre-obtained Token

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

Common Auth Errors

| Error | Fix | |-------|-----| | "Access blocked" | Add yourself as test user in OAuth consent screen | | "Google hasn't verified this app" | Click "Continue" (expected in testing mode) | | "invalid_scope" | Unverified apps limited to ~25 scopes — reduce requested scopes | | "redirect_uri_mismatch" | Add http://localhost to Authorized Redirect URIs in GCP Console | | 403 on API call | Enable the required API in Google Cloud Console, wait a few seconds |

Reset auth: gws auth logout then gws auth login

Credentials storage: Encrypted with AES-256-GCM, stored in OS keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service). Tokens auto-refresh.

---

Command Structure

All commands follow:

gws <service> <resource> <method> [--params '<json>'] [flags]

Commands are dynamically generated from Google's Discovery Service at runtime. When Google adds an API endpoint, gws picks it up automatically (discovery docs cached 24 hours).

Core Services & Examples

Google Drive

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

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

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

# Move a file to a folder
gws drive files update --params '{"addParents": "FOLDER_ID", "removeParents": "OLD_PARENT_ID"}' --file-id FILE_ID

Gmail

# List recent messages
gws gmail messages list --params '{"maxResults": 5}'

# Read a specific message
gws gmail messages get --params '{"id": "MESSAGE_ID", "format": "full"}'

# Send an email
gws gmail messages send --params '{"raw": "BASE64_ENCODED_RFC822"}'

Google Sheets

# Read values from a range
gws sheets spreadsheets.values get --params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:D10"}'

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

# Update cells
gws sheets spreadsheets.values update --params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!B2", "valueInputOption": "RAW", "requestBody": {"values": [[100]]}}'

Google Docs

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

# Get document content
gws docs documents get --params '{"documentId": "DOC_ID"}'

Google Calendar

# List upcoming events
gws calendar events list --params '{"calendarId": "primary", "maxResults": 10, "timeMin": "2026-03-08T00:00:00Z"}'

# Create an event
gws calendar events insert --params '{"calendarId": "primary", "requestBody": {"summary": "Team Sync", "start": {"dateTime": "2026-03-10T14:00:00Z"}, "end": {"dateTime": "2026-03-10T15:00:00Z"}}}'

Google Chat

# List spaces
gws chat spaces list

# Send a message to a space
gws chat spaces.messages create --params '{"parent": "spaces/SPACE_ID", "requestBody": {"text": "Hello from gws!"}}'

Admin / Directory

# List users in domain
gws admin directory users list --params '{"domain": "example.com"}'

# Get user info
gws admin directory users get --params '{"userKey": "[email protected]"}'

Discovering Available Commands

# List all available services
gws help

# List resources/methods for a service
gws drive help
gws sheets help

# Get method details
gws drive files list --help

---

MCP Server Mode

gws includes a built-in MCP (Model Context Protocol) server that exposes Google Workspace APIs as structured tools over stdio.

Starting the MCP Server

# Specific services (recommended — principle of least privilege)
gws mcp -s drive,sheets,docs

# All services
gws mcp -s all

# Single service
gws mcp -s gmail

Tool Modes

| Mode | Tools Exposed | Context Cost | Best For | |------|--------------|--------------|----------| | full (default) | 200-400 individual tools | High | When you need all methods upfront | | compact | ~26 tools (1 per service + gws_discover) | Low | Agents with limited context windows |

# Compact mode (recommended for agents)
gws mcp -s drive,sheets,calendar --tool-mode compact

In compact mode, the gws_discover meta-tool lets the agent explore available methods on demand without loading all tool definitions upfront.

Claude Code MCP Configuration

Add to your Claude settings (e.g., ~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@googleworkspace/cli", "mcp", "-s", "drive,sheets,docs,calendar", "--tool-mode", "compact"]
    }
  }
}

Service filtering (-s flag) is a security boundary — only expose services the agent actually needs. Don't use -s all unless necessary.

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@googleworkspace/cli", "mcp", "-s", "drive,sheets,docs", "--tool-mode", "compact"]
    }
  }
}

---

Agent Workflow Patterns

Pattern 1: CLI-First (Bash Tool)

Use gws directly via Bash when you need quick, one-off operations:

# Check auth before any operation
gws auth status

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

Always check gws auth status first. If not authenticated, guide the user through gws auth login.

Pattern 2: MCP-First (Structured Tools)

When the MCP server is configured, use the exposed tools directly (they appear as MCP tools in Claude Code). The compact mode gws_discover tool helps find the right method:

1. Call gws_discover with the service name to see available methods
2. Call the service-specific tool (e.g., drive_tool) with the discovered method and params
3. Parse the structured JSON response

Pattern 3: Scripted Automation

For multi-step workflows, chain commands:

# Create folder, upload file, share with team
FOLDER_ID=$(gws drive files create --params '{"name": "Sprint 42", "mimeType": "application/vnd.google-apps.folder"}' | jq -r '.id')
gws drive files create --params "{\"name\": \"retro.md\", \"parents\": [\"$FOLDER_ID\"]}" --upload ./retro.md
gws drive permissions create --params "{\"fileId\": \"$FOLDER_ID\", \"requestBody\": {\"role\": \"writer\", \"type\": \"group\", \"emailAddress\": \"[email protected]\"}}"

---

Security Rules

1. Never expose OAuth tokens or credentials in logs, output, or tool responses
2. Validate file paths — prevent directory traversal when handling paths from untrusted input
3. URL-encode user-supplied values embedded in URL path segments
4. Use --sanitize flag when processing untrusted input (enables Google Model Armor for prompt injection detection)
5. Principle of least privilege — use -s to expose only needed services via MCP
6. Never store credentials in code — rely on OS keyring (automatic) or environment variables

---

Environment Variables

| Variable | Purpose | |----------|---------| | GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE | Path to service account JSON | | GOOGLE_WORKSPACE_CLI_CLIENT_ID | OAuth client ID override | | GOOGLE_WORKSPACE_CLI_CLIENT_SECRET | OAuth client secret override | | GOOGLE_WORKSPACE_CLI_CONFIG_DIR | Override config dir (default: ~/.config/gws) | | GOOGLE_WORKSPACE_CLI_TOKEN | Pre-obtained OAuth access token |

---

Error Handling

| Error | Cause | Fix | |-------|-------|-----| | 401 Unauthorized | Token expired or invalid | gws auth login to re-authenticate | | 403 Forbidden | API not enabled or insufficient permissions | Enable the API in GCP Console; check OAuth scopes | | 404 Not Found | Wrong resource ID or API not enabled | Verify the ID; enable the API in GCP Console | | 429 Rate Limited | Too many requests | Back off and retry with exponential delay | | "command not found: gws" | Not installed | npm install -g @googleworkspace/cli | | JSON parse error in --params | Malformed JSON | Validate JSON before passing; use single quotes around the JSON string |

---

Output Format

All gws commands return structured JSON. Parse with jq for scripting:

# Get just file names
gws drive files list --params '{"pageSize": 5}' | jq -r '.files[].name'

# Get event times
gws calendar events list --params '{"calendarId": "primary", "maxResults": 3}' | jq '.items[] | {summary, start: .start.dateTime}'

---

Limitations (Pre-v1.0)

• Breaking changes may occur between minor versions
• Unverified OAuth apps are limited to ~25 scopes (may need to verify your app for full access)
• Not an official Google product — no enterprise SLA
• Discovery document caching (24h) means very new APIs may take a day to appear
• Pull requests from external contributors temporarily disabled on the upstream repo