133 lines
4.5 KiB
Markdown
133 lines
4.5 KiB
Markdown
# 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 <service> <resource> [sub-resource] <method> [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 <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
|
|
```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`
|