claude-home/productivity/google-workspace-cli.md

Google Workspace CLI (gws)

Overview

gws is a unified CLI for all Google Workspace APIs — Drive, Gmail, Calendar, Sheets, and more. It reads Google's Discovery Service at runtime and builds its command surface dynamically. Installed for use by Claude via Bash for querying and managing Google Workspace resources.

• Binary: /usr/local/bin/gws | Version: 0.11.1
• Repo: https://github.com/googleworkspace/cli
• Config dir: ~/.config/gws/
• Not an officially supported Google product

Dependencies

• gcloud SDK: /opt/google-cloud-sdk/ (added to fish PATH via config.fish)
• Node.js 18+: Required for npm install route

Authentication

• OAuth scopes authenticated: drive, gmail, calendar, sheets
• Google Cloud project: "Claude Home"
• Credentials encrypted at rest (AES-256-GCM) via OS keyring
• Cal added as test user on OAuth consent screen (required for unverified/testing apps)
• Unverified apps limited to ~25 scopes — use gws auth login -s service1,service2 to stay under limit

Re-authenticating or Adding Scopes

gws auth login -s drive,gmail,calendar,sheets,docs

Usage

Command Structure

gws <service> <resource> [sub-resource] <method> [flags]

Subcommands are space-separated (not dot-notation):

gws sheets spreadsheets values get    # correct
gws sheets spreadsheets.values get    # WRONG

Common Commands

Drive

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

# Search files
gws drive files list --params '{"q": "name contains \"keyword\""}'

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

Sheets

# Read cells — use \u0021 for ! in double-quoted JSON (bash history expansion)
gws sheets spreadsheets values get \
  --params "{\"spreadsheetId\": \"SHEET_ID\", \"range\": \"SheetName\u0021A1:Z50\"}"

# Or use single quotes (safe in fish, careful in bash)
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:C10"}'

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

# List all tabs in a spreadsheet
gws sheets spreadsheets get --params '{"spreadsheetId": "ID", "fields": "sheets.properties.title"}'

Gmail

# List unread messages
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"}'

Calendar

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

Flags Reference

Flag	Description	Default
--params <JSON>	URL/Query parameters	—
--json <JSON>	Request body (POST/PATCH/PUT)	—
--upload <PATH>	File to upload (multipart)	—
--output <PATH>	Output file for binary responses	—
--format <FMT>	Output: json, table, yaml, csv	json
--page-all	Auto-paginate as NDJSON	off
--page-limit <N>	Max pages with --page-all	10
--dry-run	Preview request without executing	off

Introspecting APIs

# See full schema for any method
gws schema drive.files.list
gws schema sheets.spreadsheets.values.get

Known Gotchas

• Sheets ! in ranges: Bash history expansion mangles !. Use \u0021 in double-quoted JSON, or single quotes
• Scope limit: Unverified OAuth apps cap at ~25 scopes. Specify only needed services with -s
• No MCP server mode: Use via Bash only — all output is structured JSON
• First run may be slow: Discovery service data is fetched and cached (24-hour cache)

Key Spreadsheets

ID	Description
1ctsjx41Muy5QXvVGvpT_8ovBc5HP_YLSJSqNRUOYidM	SBA scorecard s13w12g04 (DEN vs WV)
1K7OBSrXY3NIXUaFLn4DZRI1_P7yv-5uaVSHLSEdx1VY	Master Umpire Central
1QU5hTrNp8GuKi4FJ6AigPT54J0JtEzXzgR_6-dieWnQ	Seaglass Data

Troubleshooting

"gcloud CLI not found"

gcloud isn't in PATH. In fish: source ~/.config/fish/config.fish or restart terminal.

"Access blocked" on login

Add yourself as a test user in Google Cloud Console → APIs & Services → OAuth consent screen → Test users.

"Google hasn't verified this app" warning

Expected for testing mode. Click "Continue" to proceed.

Too many scopes error

Use -s flag to limit: gws auth login -s drive,gmail,calendar,sheets