4b7eca8a46
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 3s
Adds title, description, type, domain, and tags frontmatter to every doc for improved KB semantic search. The description field is prepended to every search chunk, and domain/type/tags enable filtered queries. Type values: context, guide, runbook, reference, troubleshooting Domain values match directory structure (networking, docker, etc.) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
141 lines
4.9 KiB
Markdown
141 lines
4.9 KiB
Markdown
---
|
|
title: "Google Workspace CLI Reference"
|
|
description: "Reference for gws, a unified CLI for Google Drive, Gmail, Calendar, and Sheets APIs. Covers authentication, command structure, common operations, Sheets range escaping, and key spreadsheet IDs."
|
|
type: reference
|
|
domain: productivity
|
|
tags: [gws, google-workspace, drive, gmail, calendar, sheets, oauth, cli]
|
|
---
|
|
|
|
# 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`
|