/google-workspace

name: google-workspace
description: >
  Manage Google Workspace via the gws CLI — Drive, Gmail, Sheets, Docs, Slides,
  People, Chat, Meet, Forms, and cross-service workflows. Use when asked to
  send email, read/write spreadsheets, upload files to Drive, manage contacts,
  create presentations, send Chat messages, create docs, or any Google Workspace
  operation. Also triggers on "gws", "Google Drive", "Google Sheets", "Gmail",
  "Google Docs", "Google Slides", "Google Chat", "Google Meet", "Google Forms",
  "check my inbox", "upload to Drive", "read spreadsheet", "send an email",
  "create a doc", "send a chat message", "create a presentation".

Google Workspace CLI (`gws`)

Interact with Google Workspace services via the `gws` CLI. This skill covers all supported services, helper shortcuts, cross-service workflows, role-based personas, and multi-step recipes.

Installation & Auth

The `gws` binary must be on `$PATH`. Version: 0.16.0+.

# Browser-based OAuth (interactive)
gws auth login

# Service Account
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

# Check status
gws auth status

Auth Flags

| Flag | Description | |------|-------------| | `--readonly` | Request read-only scopes | | `--full` | Request all scopes incl. pubsub + cloud-platform | | `--scopes` | Comma-separated custom scopes | | `-s, --services` | Limit scope picker to specific services (e.g. `-s drive,gmail`) |

CLI Syntax

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

Global Flags

| Flag | Description | |------|-------------| | `--format <FMT>` | Output format: `json` (default), `table`, `yaml`, `csv` | | `--dry-run` | Validate locally without calling the API | | `--sanitize <TEMPLATE>` | Screen responses through Model Armor | | `--params '{"key": "val"}'` | URL/query parameters | | `--json '{"key": "val"}'` | Request body | | `-o, --output <PATH>` | Save binary responses to file | | `--upload <PATH>` | Upload file content (multipart) | | `--page-all` | Auto-paginate (NDJSON output) | | `--page-limit <N>` | Max pages with --page-all (default: 10) | | `--page-delay <MS>` | Delay between pages in ms (default: 100) |

Discovering Commands

gws <service> --help                    # Browse resources and methods
gws schema <service.resource.method>    # Inspect params, types, defaults

Shell Tips

• **zsh `!` expansion:** Use double quotes for sheet ranges: `--range "Sheet1!A1:D10"`
• **JSON with double quotes:** Wrap `--params`/`--json` in single quotes: `--params '{"pageSize": 5}'`

Security Rules

• **Never** output secrets (API keys, tokens) directly
• **Always** confirm with user before executing write/delete commands
• Prefer `--dry-run` for destructive operations
• Use `--sanitize` for PII/content safety screening

Services

Core Google Workspace API skills. Read the reference file for full resource/method details.

| Service | Description | Reference | |---------|-------------|-----------| | Drive | Manage files, folders, shared drives | [references/gws-drive.md](references/gws-drive.md) | | Sheets | Read and write spreadsheets | [references/gws-sheets.md](references/gws-sheets.md) | | Gmail | Send, read, and manage email | [references/gws-gmail.md](references/gws-gmail.md) | | Docs | Read and write Google Docs | [references/gws-docs.md](references/gws-docs.md) | | Slides | Read and write presentations | [references/gws-slides.md](references/gws-slides.md) | | People | Manage contacts and profiles | [references/gws-people.md](references/gws-people.md) | | Chat | Manage Chat spaces and messages | [references/gws-chat.md](references/gws-chat.md) | | Meet | Manage Google Meet conferences | [references/gws-meet.md](references/gws-meet.md) | | Forms | Read and write Google Forms | [references/gws-forms.md](references/gws-forms.md) | | Admin Reports | Audit logs and usage reports | [references/gws-admin-reports.md](references/gws-admin-reports.md) | | Events | Subscribe to Workspace events | [references/gws-events.md](references/gws-events.md) | | Keep | Manage Google Keep notes | [references/gws-keep.md](references/gws-keep.md) | | Classroom | Manage courses, students, and invitations | [references/gws-classroom.md](references/gws-classroom.md) | | Model Armor | Filter content for safety | [references/gws-modelarmor.md](references/gws-modelarmor.md) | | Workflow | Cross-service productivity workflows | [references/gws-workflow.md](references/gws-workflow.md) |

Helper Shortcuts

Quick commands for common operations. Read the reference file for flags and examples.

Drive

| Command | Reference | |---------|-----------| | `gws drive +upload <file>` | [references/gws-drive-upload.md](references/gws-drive-upload.md) |

Sheets

| Command | Reference | |---------|-----------| | `gws sheets +read --spreadsheet ID --range RANGE` | [references/gws-sheets-read.md](references/gws-sheets-read.md) | | `gws sheets +append --spreadsheet ID --values '...'` | [references/gws-sheets-append.md](references/gws-sheets-append.md) |

Gmail

| Command | Reference | |---------|-----------| | `gws gmail +send --to EMAIL --subject S --body B` | [references/gws-gmail-send.md](references/gws-gmail-send.md) | | `gws gmail +triage` | [references/gws-gmail-triage.md](references/gws-gmail-triage.md) | | `gws gmail +reply --message-id ID --body TEXT` | [references/gws-gmail-reply.md](references/gws-gmail-reply.md) | | `gws gmail +reply-all --message-id ID --body TEXT` | [references/gws-gmail-reply-all.md](references/gws-gmail-reply-all.md) | | `gws gmail +forward --message-id ID --to EMAIL` | [references/gws-gmail-forward.md](references/gws-gmail-forward.md) | | `gws gmail +watch` | [references/gws-gmail-watch.md](references/gws-gmail-watch.md) |

Docs

| Command | Reference | |---------|-----------| | `gws docs +write --document ID --text TEXT` | [references/gws-docs-write.md](references/gws-docs-write.md) |

Chat

| Command | Reference | |--