From e2ec022a3347bd6d286fbdfca64d0824b75ef20c Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Thu, 12 Mar 2026 07:40:35 -0500 Subject: [PATCH] docs: add Google Workspace CLI documentation Co-Authored-By: Claude Opus 4.6 --- productivity/CONTEXT.md | 6 ++ productivity/google-workspace-cli.md | 132 +++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 productivity/google-workspace-cli.md diff --git a/productivity/CONTEXT.md b/productivity/CONTEXT.md index 0eaf50e..a428bd1 100644 --- a/productivity/CONTEXT.md +++ b/productivity/CONTEXT.md @@ -3,6 +3,12 @@ ## Overview ADHD-optimized task management system designed to break the context-switching spiral. The system uses a persistent terminal dashboard with zero-friction brain dump capture to help maintain focus while capturing interrupting thoughts. +## Google Workspace CLI (gws) +Unified CLI for Drive, Gmail, Calendar, Sheets, and all Google Workspace APIs. Dynamically discovers API endpoints at runtime. +- **Binary**: `/usr/local/bin/gws` | **Version**: 0.11.1 +- **gcloud SDK**: `/opt/google-cloud-sdk/` +- **Docs**: [google-workspace-cli.md](google-workspace-cli.md) + ## Handy - Speech to Text Desktop speech-to-text app with system tray integration. Installed via RPM from GitHub. - **Binary**: `/usr/bin/handy` | **Version**: 0.7.6 diff --git a/productivity/google-workspace-cli.md b/productivity/google-workspace-cli.md new file mode 100644 index 0000000..d5c997b --- /dev/null +++ b/productivity/google-workspace-cli.md @@ -0,0 +1,132 @@ +# 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 +```bash +gws auth login -s drive,gmail,calendar,sheets,docs +``` + +## Usage + +### Command Structure +``` +gws [sub-resource] [flags] +``` + +Subcommands are **space-separated** (not dot-notation): +```bash +gws sheets spreadsheets values get # correct +gws sheets spreadsheets.values get # WRONG +``` + +### Common Commands + +#### Drive +```bash +# 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 +```bash +# 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 +```bash +# 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 +```bash +# List upcoming events +gws calendar events list --params '{"calendarId": "primary", "maxResults": 5}' +``` + +### Flags Reference +| Flag | Description | Default | +|------|-------------|---------| +| `--params ` | URL/Query parameters | — | +| `--json ` | Request body (POST/PATCH/PUT) | — | +| `--upload ` | File to upload (multipart) | — | +| `--output ` | Output file for binary responses | — | +| `--format ` | Output: json, table, yaml, csv | json | +| `--page-all` | Auto-paginate as NDJSON | off | +| `--page-limit ` | Max pages with --page-all | 10 | +| `--dry-run` | Preview request without executing | off | + +### Introspecting APIs +```bash +# 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`