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 |
| Sheets |
Read and write spreadsheets |
references/gws-sheets.md |
| Gmail |
Send, read, and manage email |
references/gws-gmail.md |
| Docs |
Read and write Google Docs |
references/gws-docs.md |
| Slides |
Read and write presentations |
references/gws-slides.md |
| People |
Manage contacts and profiles |
references/gws-people.md |
| Chat |
Manage Chat spaces and messages |
references/gws-chat.md |
| Meet |
Manage Google Meet conferences |
references/gws-meet.md |
| Forms |
Read and write Google Forms |
references/gws-forms.md |
| Admin Reports |
Audit logs and usage reports |
references/gws-admin-reports.md |
| Events |
Subscribe to Workspace events |
references/gws-events.md |
| Keep |
Manage Google Keep notes |
references/gws-keep.md |
| Classroom |
Manage courses, students, and invitations |
references/gws-classroom.md |
| Model Armor |
Filter content for safety |
references/gws-modelarmor.md |
| Workflow |
Cross-service productivity workflows |
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 |
Sheets
| Command |
Reference |
gws sheets +read --spreadsheet ID --range RANGE |
references/gws-sheets-read.md |
gws sheets +append --spreadsheet ID --values '...' |
references/gws-sheets-append.md |
Gmail
| Command |
Reference |
gws gmail +send --to EMAIL --subject S --body B |
references/gws-gmail-send.md |
gws gmail +triage |
references/gws-gmail-triage.md |
gws gmail +reply --message-id ID --body TEXT |
references/gws-gmail-reply.md |
gws gmail +reply-all --message-id ID --body TEXT |
references/gws-gmail-reply-all.md |
gws gmail +forward --message-id ID --to EMAIL |
references/gws-gmail-forward.md |
gws gmail +watch |
references/gws-gmail-watch.md |
Docs
| Command |
Reference |
gws docs +write --document ID --text TEXT |
references/gws-docs-write.md |
Chat
| Command |
Reference |
gws chat +send --space NAME --text TEXT |
references/gws-chat-send.md |
Events
| Command |
Reference |
gws events +subscribe |
references/gws-events-subscribe.md |
gws events +renew |
references/gws-events-renew.md |
Model Armor
| Command |
Reference |
gws modelarmor +sanitize-prompt --template NAME |
references/gws-modelarmor-sanitize-prompt.md |
gws modelarmor +sanitize-response --template NAME |
references/gws-modelarmor-sanitize-response.md |
gws modelarmor +create-template --project P --location L --template-id ID |
references/gws-modelarmor-create-template.md |
Workflow
| Command |
Reference |
gws workflow +standup-report |
references/gws-workflow-standup-report.md |
gws workflow +meeting-prep |
references/gws-workflow-meeting-prep.md |
gws workflow +email-to-task --message-id ID |
references/gws-workflow-email-to-task.md |
gws workflow +weekly-digest |
references/gws-workflow-weekly-digest.md |
gws workflow +file-announce --file-id ID --space SPACE |
references/gws-workflow-file-announce.md |
Personas
Role-based skill bundles for common workflows. Read the reference for instructions.
| Persona |
Description |
Reference |
| Executive Assistant |
Schedule, inbox, and communications |
references/persona-exec-assistant.md |
| Project Manager |
Tasks, meetings, and doc sharing |
references/persona-project-manager.md |
| Team Lead |
Standups, coordination, and comms |
references/persona-team-lead.md |
| Sales Operations |
Deal tracking, calls, client comms |
references/persona-sales-ops.md |
| Content Creator |
Create, organize, distribute content |
references/persona-content-creator.md |
| Event Coordinator |
Scheduling, invitations, logistics |
references/persona-event-coordinator.md |
| Customer Support |
Tickets, responses, escalation |
references/persona-customer-support.md |
| HR Coordinator |
Onboarding, announcements, comms |
references/persona-hr-coordinator.md |
| IT Administrator |
Security monitoring, configuration |
references/persona-it-admin.md |
| Researcher |
References, notes, collaboration |
references/persona-researcher.md |
Recipes
Multi-step task sequences with real commands. Read the reference for step-by-step instructions.
Gmail Recipes
| Recipe |
Reference |
| Label and archive emails |
references/recipe-label-and-archive-emails.md |
| Create Gmail filter |
references/recipe-create-gmail-filter.md |
| Forward labeled emails |
references/recipe-forward-labeled-emails.md |
| Set vacation responder |
references/recipe-create-vacation-responder.md |
| Save email attachments to Drive |
references/recipe-save-email-attachments.md |
| Save email to Google Doc |
references/recipe-save-email-to-doc.md |
| Draft email from Doc |
references/recipe-draft-email-from-doc.md |
Drive Recipes
| Recipe |
Reference |
| Organize Drive folder |
references/recipe-organize-drive-folder.md |
| Share folder with team |
references/recipe-share-folder-with-team.md |
| Email a Drive link |
references/recipe-email-drive-link.md |
| Bulk download folder |
references/recipe-bulk-download-folder.md |
| Find large files |
references/recipe-find-large-files.md |
| Create shared drive |
references/recipe-create-shared-drive.md |
| Watch Drive changes |
references/recipe-watch-drive-changes.md |
Sheets Recipes
| Recipe |
Reference |
| Create expense tracker |
references/recipe-create-expense-tracker.md |
| Copy sheet for new month |
references/recipe-copy-sheet-for-new-month.md |
| Log deal update |
references/recipe-log-deal-update.md |
| Compare sheet tabs |
references/recipe-compare-sheet-tabs.md |
| Backup sheet as CSV |
references/recipe-backup-sheet-as-csv.md |
| Sync contacts to sheet |
references/recipe-sync-contacts-to-sheet.md |
| Generate report from sheet |
references/recipe-generate-report-from-sheet.md |
Cross-Service Recipes
| Recipe |
Reference |
| Create doc from template |
references/recipe-create-doc-from-template.md |
| Share doc and notify |
references/recipe-share-doc-and-notify.md |
| Send team announcement |
references/recipe-send-team-announcement.md |
| Create feedback form |
references/recipe-create-feedback-form.md |
| Create Meet space |
references/recipe-create-meet-space.md |
| Review Meet participants |
references/recipe-review-meet-participants.md |
| Create presentation |
references/recipe-create-presentation.md |
| Collect form responses |
references/recipe-collect-form-responses.md |
| Create classroom course |
references/recipe-create-classroom-course.md |
Exit Codes
| Code |
Meaning |
| 0 |
Success |
| 1 |
API error — Google returned an error response |
| 2 |
Auth error — credentials missing or invalid |
| 3 |
Validation — bad arguments or input |
| 4 |
Discovery — could not fetch API schema |
| 5 |
Internal — unexpected failure |
Community & Feedback
1---2name: google-workspace3description: 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".4---56# Google Workspace CLI (`gws`)78Interact with Google Workspace services via the `gws` CLI. This skill covers9all supported services, helper shortcuts, cross-service workflows, role-based10personas, and multi-step recipes.1112## Installation & Auth1314The `gws` binary must be on `$PATH`. Version: 0.16.0+.1516```bash17# Browser-based OAuth (interactive)18gws auth login1920# Service Account21export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json2223# Check status24gws auth status25```2627### Auth Flags2829| Flag | Description |30|------|-------------|31| `--readonly` | Request read-only scopes |32| `--full` | Request all scopes incl. pubsub + cloud-platform |33| `--scopes` | Comma-separated custom scopes |34| `-s, --services` | Limit scope picker to specific services (e.g. `-s drive,gmail`) |3536## CLI Syntax3738```bash39gws <service> <resource> [sub-resource] <method> [flags]40```4142### Global Flags4344| Flag | Description |45|------|-------------|46| `--format <FMT>` | Output format: `json` (default), `table`, `yaml`, `csv` |47| `--dry-run` | Validate locally without calling the API |48| `--sanitize <TEMPLATE>` | Screen responses through Model Armor |49| `--params '{"key": "val"}'` | URL/query parameters |50| `--json '{"key": "val"}'` | Request body |51| `-o, --output <PATH>` | Save binary responses to file |52| `--upload <PATH>` | Upload file content (multipart) |53| `--page-all` | Auto-paginate (NDJSON output) |54| `--page-limit <N>` | Max pages with --page-all (default: 10) |55| `--page-delay <MS>` | Delay between pages in ms (default: 100) |5657### Discovering Commands5859```bash60gws <service> --help # Browse resources and methods61gws schema <service.resource.method> # Inspect params, types, defaults62```6364## Shell Tips6566- **zsh `!` expansion:** Use double quotes for sheet ranges: `--range "Sheet1!A1:D10"`67- **JSON with double quotes:** Wrap `--params`/`--json` in single quotes: `--params '{"pageSize": 5}'`6869## Security Rules7071- **Never** output secrets (API keys, tokens) directly72- **Always** confirm with user before executing write/delete commands73- Prefer `--dry-run` for destructive operations74- Use `--sanitize` for PII/content safety screening7576## Services7778Core Google Workspace API skills. Read the reference file for full resource/method details.7980| Service | Description | Reference |81|---------|-------------|-----------|82| Drive | Manage files, folders, shared drives | [references/gws-drive.md](references/gws-drive.md) |83| Sheets | Read and write spreadsheets | [references/gws-sheets.md](references/gws-sheets.md) |84| Gmail | Send, read, and manage email | [references/gws-gmail.md](references/gws-gmail.md) |85| Docs | Read and write Google Docs | [references/gws-docs.md](references/gws-docs.md) |86| Slides | Read and write presentations | [references/gws-slides.md](references/gws-slides.md) |87| People | Manage contacts and profiles | [references/gws-people.md](references/gws-people.md) |88| Chat | Manage Chat spaces and messages | [references/gws-chat.md](references/gws-chat.md) |89| Meet | Manage Google Meet conferences | [references/gws-meet.md](references/gws-meet.md) |90| Forms | Read and write Google Forms | [references/gws-forms.md](references/gws-forms.md) |91| Admin Reports | Audit logs and usage reports | [references/gws-admin-reports.md](references/gws-admin-reports.md) |92| Events | Subscribe to Workspace events | [references/gws-events.md](references/gws-events.md) |93| Keep | Manage Google Keep notes | [references/gws-keep.md](references/gws-keep.md) |94| Classroom | Manage courses, students, and invitations | [references/gws-classroom.md](references/gws-classroom.md) |95| Model Armor | Filter content for safety | [references/gws-modelarmor.md](references/gws-modelarmor.md) |96| Workflow | Cross-service productivity workflows | [references/gws-workflow.md](references/gws-workflow.md) |9798## Helper Shortcuts99100Quick commands for common operations. Read the reference file for flags and examples.101102### Drive103| Command | Reference |104|---------|-----------|105| `gws drive +upload <file>` | [references/gws-drive-upload.md](references/gws-drive-upload.md) |106107### Sheets108| Command | Reference |109|---------|-----------|110| `gws sheets +read --spreadsheet ID --range RANGE` | [references/gws-sheets-read.md](references/gws-sheets-read.md) |111| `gws sheets +append --spreadsheet ID --values '...'` | [references/gws-sheets-append.md](references/gws-sheets-append.md) |112113### Gmail114| Command | Reference |115|---------|-----------|116| `gws gmail +send --to EMAIL --subject S --body B` | [references/gws-gmail-send.md](references/gws-gmail-send.md) |117| `gws gmail +triage` | [references/gws-gmail-triage.md](references/gws-gmail-triage.md) |118| `gws gmail +reply --message-id ID --body TEXT` | [references/gws-gmail-reply.md](references/gws-gmail-reply.md) |119| `gws gmail +reply-all --message-id ID --body TEXT` | [references/gws-gmail-reply-all.md](references/gws-gmail-reply-all.md) |120| `gws gmail +forward --message-id ID --to EMAIL` | [references/gws-gmail-forward.md](references/gws-gmail-forward.md) |121| `gws gmail +watch` | [references/gws-gmail-watch.md](references/gws-gmail-watch.md) |122123### Docs124| Command | Reference |125|---------|-----------|126| `gws docs +write --document ID --text TEXT` | [references/gws-docs-write.md](references/gws-docs-write.md) |127128### Chat129| Command | Reference |130|---------|-----------|131| `gws chat +send --space NAME --text TEXT` | [references/gws-chat-send.md](references/gws-chat-send.md) |132133### Events134| Command | Reference |135|---------|-----------|136| `gws events +subscribe` | [references/gws-events-subscribe.md](references/gws-events-subscribe.md) |137| `gws events +renew` | [references/gws-events-renew.md](references/gws-events-renew.md) |138139### Model Armor140| Command | Reference |141|---------|-----------|142| `gws modelarmor +sanitize-prompt --template NAME` | [references/gws-modelarmor-sanitize-prompt.md](references/gws-modelarmor-sanitize-prompt.md) |143| `gws modelarmor +sanitize-response --template NAME` | [references/gws-modelarmor-sanitize-response.md](references/gws-modelarmor-sanitize-response.md) |144| `gws modelarmor +create-template --project P --location L --template-id ID` | [references/gws-modelarmor-create-template.md](references/gws-modelarmor-create-template.md) |145146### Workflow147| Command | Reference |148|---------|-----------|149| `gws workflow +standup-report` | [references/gws-workflow-standup-report.md](references/gws-workflow-standup-report.md) |150| `gws workflow +meeting-prep` | [references/gws-workflow-meeting-prep.md](references/gws-workflow-meeting-prep.md) |151| `gws workflow +email-to-task --message-id ID` | [references/gws-workflow-email-to-task.md](references/gws-workflow-email-to-task.md) |152| `gws workflow +weekly-digest` | [references/gws-workflow-weekly-digest.md](references/gws-workflow-weekly-digest.md) |153| `gws workflow +file-announce --file-id ID --space SPACE` | [references/gws-workflow-file-announce.md](references/gws-workflow-file-announce.md) |154155## Personas156157Role-based skill bundles for common workflows. Read the reference for instructions.158159| Persona | Description | Reference |160|---------|-------------|-----------|161| Executive Assistant | Schedule, inbox, and communications | [references/persona-exec-assistant.md](references/persona-exec-assistant.md) |162| Project Manager | Tasks, meetings, and doc sharing | [references/persona-project-manager.md](references/persona-project-manager.md) |163| Team Lead | Standups, coordination, and comms | [references/persona-team-lead.md](references/persona-team-lead.md) |164| Sales Operations | Deal tracking, calls, client comms | [references/persona-sales-ops.md](references/persona-sales-ops.md) |165| Content Creator | Create, organize, distribute content | [references/persona-content-creator.md](references/persona-content-creator.md) |166| Event Coordinator | Scheduling, invitations, logistics | [references/persona-event-coordinator.md](references/persona-event-coordinator.md) |167| Customer Support | Tickets, responses, escalation | [references/persona-customer-support.md](references/persona-customer-support.md) |168| HR Coordinator | Onboarding, announcements, comms | [references/persona-hr-coordinator.md](references/persona-hr-coordinator.md) |169| IT Administrator | Security monitoring, configuration | [references/persona-it-admin.md](references/persona-it-admin.md) |170| Researcher | References, notes, collaboration | [references/persona-researcher.md](references/persona-researcher.md) |171172## Recipes173174Multi-step task sequences with real commands. Read the reference for step-by-step instructions.175176### Gmail Recipes177| Recipe | Reference |178|--------|-----------|179| Label and archive emails | [references/recipe-label-and-archive-emails.md](references/recipe-label-and-archive-emails.md) |180| Create Gmail filter | [references/recipe-create-gmail-filter.md](references/recipe-create-gmail-filter.md) |181| Forward labeled emails | [references/recipe-forward-labeled-emails.md](references/recipe-forward-labeled-emails.md) |182| Set vacation responder | [references/recipe-create-vacation-responder.md](references/recipe-create-vacation-responder.md) |183| Save email attachments to Drive | [references/recipe-save-email-attachments.md](references/recipe-save-email-attachments.md) |184| Save email to Google Doc | [references/recipe-save-email-to-doc.md](references/recipe-save-email-to-doc.md) |185| Draft email from Doc | [references/recipe-draft-email-from-doc.md](references/recipe-draft-email-from-doc.md) |186187### Drive Recipes188| Recipe | Reference |189|--------|-----------|190| Organize Drive folder | [references/recipe-organize-drive-folder.md](references/recipe-organize-drive-folder.md) |191| Share folder with team | [references/recipe-share-folder-with-team.md](references/recipe-share-folder-with-team.md) |192| Email a Drive link | [references/recipe-email-drive-link.md](references/recipe-email-drive-link.md) |193| Bulk download folder | [references/recipe-bulk-download-folder.md](references/recipe-bulk-download-folder.md) |194| Find large files | [references/recipe-find-large-files.md](references/recipe-find-large-files.md) |195| Create shared drive | [references/recipe-create-shared-drive.md](references/recipe-create-shared-drive.md) |196| Watch Drive changes | [references/recipe-watch-drive-changes.md](references/recipe-watch-drive-changes.md) |197198### Sheets Recipes199| Recipe | Reference |200|--------|-----------|201| Create expense tracker | [references/recipe-create-expense-tracker.md](references/recipe-create-expense-tracker.md) |202| Copy sheet for new month | [references/recipe-copy-sheet-for-new-month.md](references/recipe-copy-sheet-for-new-month.md) |203| Log deal update | [references/recipe-log-deal-update.md](references/recipe-log-deal-update.md) |204| Compare sheet tabs | [references/recipe-compare-sheet-tabs.md](references/recipe-compare-sheet-tabs.md) |205| Backup sheet as CSV | [references/recipe-backup-sheet-as-csv.md](references/recipe-backup-sheet-as-csv.md) |206| Sync contacts to sheet | [references/recipe-sync-contacts-to-sheet.md](references/recipe-sync-contacts-to-sheet.md) |207| Generate report from sheet | [references/recipe-generate-report-from-sheet.md](references/recipe-generate-report-from-sheet.md) |208209### Cross-Service Recipes210| Recipe | Reference |211|--------|-----------|212| Create doc from template | [references/recipe-create-doc-from-template.md](references/recipe-create-doc-from-template.md) |213| Share doc and notify | [references/recipe-share-doc-and-notify.md](references/recipe-share-doc-and-notify.md) |214| Send team announcement | [references/recipe-send-team-announcement.md](references/recipe-send-team-announcement.md) |215| Create feedback form | [references/recipe-create-feedback-form.md](references/recipe-create-feedback-form.md) |216| Create Meet space | [references/recipe-create-meet-space.md](references/recipe-create-meet-space.md) |217| Review Meet participants | [references/recipe-review-meet-participants.md](references/recipe-review-meet-participants.md) |218| Create presentation | [references/recipe-create-presentation.md](references/recipe-create-presentation.md) |219| Collect form responses | [references/recipe-collect-form-responses.md](references/recipe-collect-form-responses.md) |220| Create classroom course | [references/recipe-create-classroom-course.md](references/recipe-create-classroom-course.md) |221222## Exit Codes223224| Code | Meaning |225|------|---------|226| 0 | Success |227| 1 | API error — Google returned an error response |228| 2 | Auth error — credentials missing or invalid |229| 3 | Validation — bad arguments or input |230| 4 | Discovery — could not fetch API schema |231| 5 | Internal — unexpected failure |232233## Community & Feedback234235- Star the repo: https://github.com/googleworkspace/cli236- Bugs / feature requests: https://github.com/googleworkspace/cli/issues237- Always search existing issues before creating new ones
espennilsen