Gws Workspace

Google Workspace CLI (gws)

Prerequisites

1. gws must be on $PATH (npm install -g @googleworkspace/cli)
2. Auth: gws auth login (browser OAuth) or GOOGLE_APPLICATION_CREDENTIALS env var
3. Check auth: NODE_NO_WARNINGS=1 gws auth status

Important

• Always suppress Node warnings: prefix commands with NODE_NO_WARNINGS=1
• Read-only first: always confirm access with a read command before writes
• Confirm before writes: never execute write/delete without user approval
• Use --dry-run for destructive operations
• MCP fallback: If mcp__claude_ai_Gmail__* or mcp__claude_ai_Google_Calendar__* tools are available, prefer those for Gmail/Calendar tasks

Quick Reference

# Syntax
NODE_NO_WARNINGS=1 gws <service> <resource> <method> [flags]

# Inspect any method before calling
NODE_NO_WARNINGS=1 gws schema <service>.<resource>.<method>

Core Services

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

# Search
gws drive files list --params '{"q": "name contains '''report'''", "pageSize": 10}'

# Get file metadata
gws drive files get --params '{"fileId": "ID", "fields": "name,mimeType,size"}'

# Download
gws drive files get --params '{"fileId": "ID", "alt": "media"}' -o output.pdf

# Upload
gws drive +upload --file local.pdf --name "Report.pdf" --parent FOLDER_ID

# Export Google Doc as PDF
gws drive files export --params '{"fileId": "ID", "mimeType": "application/pdf"}' -o doc.pdf

# Read values
gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'

# Read entire sheet
gws sheets +read --spreadsheet ID --range Sheet1

# Append row
gws sheets +append --spreadsheet ID --range 'Sheet1!A:D' --values '[["a","b","c","d"]]'

# Get spreadsheet metadata
gws sheets spreadsheets get --params '{"spreadsheetId": "ID"}'

# Get doc metadata
gws docs documents get --params '{"documentId": "ID"}'

# Append text
gws docs +write --document ID --text "Appended text"

# Get presentation
gws slides presentations get --params '{"presentationId": "ID"}'

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

# Search
gws gmail users messages list --params '{"userId": "me", "q": "from:user@example.com"}'

# Send
gws gmail +send --to user@example.com --subject "Subject" --body "Body"

# List events
gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}'

# Insert event
gws calendar +insert --calendar primary --summary "Meeting" --start "2026-03-12T10:00:00+09:00" --end "2026-03-12T11:00:00+09:00"

Global Flags

• 401/403: Run gws auth login to re-authenticate
• 404: Verify file/spreadsheet ID is correct
• Rate limit: Add --page-delay 500 for bulk operations

Discovery

# Browse all services
gws --help

# Browse service resources
gws drive --help

# Inspect method params
gws schema drive.files.list

For detailed API reference per service, see references/ directory.