Imported from anton-abyzov/vskill (.claude/skills/google-workspace/gws/SKILL.md). Install upstream with npx skills add anton-abyzov/vskill --skill gws. Copyright stays with the author.

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

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

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": "user@example.com"}'

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

# 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\": \"engineering@company.com\"}}"

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

Error Handling

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