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
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

• Star the repo: https://github.com/googleworkspace/cli
• Bugs / feature requests: https://github.com/googleworkspace/cli/issues
• Always search existing issues before creating new ones