---
name: google-workspace
description: Interact with Google Workspace services (Drive, Sheets, Gmail, Calendar, Docs, Chat, Tasks) using the `gws` CLI. Use when users want to upload/download files from Drive, read/write spreadsheets, send emails, manage calendar events, or interact with any Google Workspace API.
---

# Google Workspace Skill

Interact with Google Workspace services via the `gws` CLI tool (Google Workspace CLI).

## Prerequisites

The `gws` CLI must be installed and authenticated:
```bash
# Install
npm install -g @googleworkspace/cli --prefix ~/.local

# Authenticate (one-time)
gws auth setup    # Creates Cloud project & enables APIs
gws auth login    # Subsequent logins
```

## Available Services

| Service | Description | Example |
|---------|-------------|---------|
| `drive` | Files, folders, shared drives | `gws drive files list` |
| `sheets` | Spreadsheets | `gws sheets spreadsheets get` |
| `gmail` | Email | `gws gmail users messages list` |
| `calendar` | Events & calendars | `gws calendar events list` |
| `docs` | Documents | `gws docs documents get` |
| `chat` | Messaging | `gws chat spaces list` |
| `tasks` | Task lists | `gws tasks tasklists list` |
| `admin` | Admin directory | `gws admin users list` |

Plus 40+ additional Google APIs via Discovery Service.

## Command Pattern

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

### Key Flags

| Flag | Description |
|------|-------------|
| `--params '<JSON>'` | URL/query parameters |
| `--json '<JSON>'` | Request body (POST/PATCH/PUT) |
| `--upload <PATH>` | File to upload |
| `--output <PATH>` | Save binary response to file |
| `--format <FMT>` | Output: json (default), table, yaml, csv |
| `--page-all` | Auto-paginate all results |
| `--dry-run` | Preview request without executing |

### Schema Introspection

To discover available parameters for any method:
```bash
gws schema drive.files.list
gws schema sheets.spreadsheets.values.get
```

## Common Operations

### Google Drive

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

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

# Download a file
gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' --output ./file.pdf

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

# Create a folder
gws drive files create --json '{"name": "New Folder", "mimeType": "application/vnd.google-apps.folder"}'
```

### Google Sheets

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

# Read cell values
gws sheets spreadsheets values get --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:D10"}'

# Write values
gws sheets spreadsheets values update \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Value"], ["foo", 42]]}'

# Append rows
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["new row", 123]]}'

# Create a new spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "My Sheet"}}'
```

### Gmail

```bash
# List recent messages
gws gmail users messages list --params '{"userId": "me", "maxResults": 5}'

# Read a message
gws gmail users messages get --params '{"userId": "me", "id": "MESSAGE_ID"}'

# Send email (helper command)
gws gmail +send --to "user@example.com" --subject "Hello" --body "Message body"
```

### Google Calendar

```bash
# List calendars
gws calendar calendarList list

# List upcoming events
gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-19T00:00:00Z", "maxResults": 10, "orderBy": "startTime", "singleEvents": true}'

# Create an event
gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{"summary": "Meeting", "start": {"dateTime": "2026-03-20T10:00:00+01:00"}, "end": {"dateTime": "2026-03-20T11:00:00+01:00"}}'
```

### Google Docs

```bash
# Get document content
gws docs documents get --params '{"documentId": "DOC_ID"}'
```

## Helper Commands (+ prefix)

Higher-level commands for common workflows:
```bash
gws gmail +send          # Send emails
gws sheets +append       # Add spreadsheet rows
gws calendar +agenda     # Show upcoming events
gws drive +upload        # Upload with metadata
```

## Tips

- Always use `--format table` for human-readable output
- Use `gws schema <service.resource.method>` to discover parameters
- Use `--dry-run` to preview requests before executing
- Use `--page-all` to get all results (streams NDJSON)
- File IDs can be extracted from Google Drive/Sheets URLs: `https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`
- For errors, check `gws auth status` to verify authentication