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