gws

Google Workspace CLI (gws)

用于 Gmail、Calendar、Drive、Sheets、Docs、Slides、Tasks、People、Chat、Meet、Forms、Keep、Admin 及跨服务工作流的命令行工具。

二进制文件：/opt/homebrew/bin/gws

命令模式

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

每条命令均接受：

• --params <JSON> — URL／查询参数
• --json <JSON> — 请求正文（POST/PATCH/PUT）
• --upload <PATH> — 作为媒体内容上传的文件
• --output <PATH> — 二进制响应的路径（下载）
• --format json|table|yaml|csv — 输出格式（默认为 json）
• --page-all / --page-limit N — 自动分页
• --dry-run — 在本地验证，不发送请求

快速参考 — 辅助命令（优先使用）

命令	用途	R/W
gws gmail +triage [--max N] [--query Q]	未读收件箱摘要	R
gws gmail +send --to EMAIL --subject S --body T	发送纯文本邮件	W
gws gmail +watch --project GCP	流式接收新邮件（Pub/Sub）	R
gws calendar +agenda [--today|--tomorrow|--week|--days N]	即将举行的活动	R
gws calendar +insert --summary T --start ISO --end ISO	创建活动	W
gws drive +upload FILE [--parent ID] [--name N]	上传文件	W
gws sheets +read --spreadsheet ID --range R	读取范围（例如 Sheet1!A1:D10）	R
gws sheets +append --spreadsheet ID --values "a,b,c"	追加行（或使用 --json-values）	W
gws docs +write --document ID --text T	向文档追加文本	W
gws chat +send --space spaces/ID --text T	在 Chat 空间中发消息	W
gws workflow +standup-report	今日会议 + 未完成任务	R
gws workflow +meeting-prep [--calendar ID]	下一场会议的详情	R
gws workflow +email-to-task --message-id ID	邮件 → 任务	W
gws workflow +weekly-digest	本周会议 + 未读邮件	R
gws workflow +file-announce --file-id ID --space SPACE	在 Chat 中发布文件公告	W

常见模式

Gmail

# Triage unread (table for humans)
gws gmail +triage --max 10 --format table

# Search
gws gmail users messages list --params '{"userId":"me","q":"from:amazon newer_than:7d","maxResults":5}'

# Read full message
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"full"}'

# Read headers only (faster)
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"metadata","metadataHeaders":["Subject","From","Date"]}'

# Archive (remove INBOX)
gws gmail users messages modify --params '{"userId":"me","id":"MSG_ID"}' --json '{"removeLabelIds":["INBOX"]}'

# Trash
gws gmail users messages trash --params '{"userId":"me","id":"MSG_ID"}'

# Bulk label
gws gmail users messages batchModify --params '{"userId":"me"}' --json '{"ids":["ID1","ID2"],"addLabelIds":["Label_123"]}'

Calendar

# Today (Europe/Berlin default works with RFC3339 +02:00/+01:00)
gws calendar +agenda --today --format table

# Create simple event
gws calendar +insert \
  --summary 'AGENCY Meetup' \
  --start '2026-04-14T18:00:00+02:00' \
  --end '2026-04-14T19:00:00+02:00' \
  --location 'https://us02web.zoom.us/j/8991032224' \
  --description 'Zoom: https://us02web.zoom.us/j/8991032224'

# Event WITH Google Meet link (helper doesn't support — use raw)
gws calendar events insert \
  --params '{"calendarId":"primary","conferenceDataVersion":1}' \
  --json '{
    "summary":"Sync",
    "start":{"dateTime":"2026-04-15T14:00:00+02:00"},
    "end":{"dateTime":"2026-04-15T15:00:00+02:00"},
    "conferenceData":{"createRequest":{"requestId":"req-'$(date +%s)'","conferenceSolutionKey":{"type":"hangoutsMeet"}}}
  }'

# Update event
gws calendar events patch --params '{"calendarId":"primary","eventId":"EID"}' --json '{"summary":"New title"}'

# Delete
gws calendar events delete --params '{"calendarId":"primary","eventId":"EID"}'

# List all calendars
gws calendar calendarList list --format table

Drive

# Upload to root
gws drive +upload ./report.pdf

# Upload to folder
gws drive +upload ./data.csv --parent FOLDER_ID --name 'Sales Data.csv'

# Search files
gws drive files list --params '{"q":"name contains \"report\" and mimeType=\"application/pdf\"","pageSize":10}'

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

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

# Share with user
gws drive permissions create --params '{"fileId":"FID"}' --json '{"role":"reader","type":"user","emailAddress":"[email protected]"}'

Sheets

# Read
gws sheets +read --spreadsheet SID --range 'Sheet1!A1:D10' --format table

# Append single row (simple values)
gws sheets +append --spreadsheet SID --values 'Alice,100,true'

# Append multiple rows
gws sheets +append --spreadsheet SID --json-values '[["a","b"],["c","d"]]'

Tasks

gws tasks tasklists list
gws tasks tasks list --params '{"tasklist":"@default"}'
gws tasks tasks insert --params '{"tasklist":"@default"}' --json '{"title":"My task","notes":"Details","due":"2026-04-20T00:00:00Z"}'
gws tasks tasks patch --params '{"tasklist":"@default","task":"TID"}' --json '{"status":"completed"}'

Chat

# Find space
gws chat spaces list --format table

# Post message
gws chat +send --space spaces/AAAAxxxx --text 'Hello team!'

People / 联系人

gws people people connections list --params '{"resourceName":"people/me","personFields":"names,emailAddresses","pageSize":100}'
gws people people searchContacts --params '{"query":"John","readMask":"names,emailAddresses"}'

重要注意事项

• userId：每次 Gmail 原始 API 调用都需要在参数中包含 "userId":"me"。
• RFC3339 时间：Calendar 使用带时区偏移的完整 ISO 格式（2026-04-14T18:00:00+02:00）。UTC 使用 “Z”。
• Meet 链接：+insert 不会添加会议功能；请使用原始 events.insert，并设置 conferenceDataVersion=1 和 conferenceData.createRequest。
• 分页：--page-all 会输出 NDJSON（每页一个 JSON 对象）。--page-limit N 用于限制页数。
• 架构发现：gws schema <service>.<resource>.<method> — 例如 gws schema gmail.users.messages.list。
• 过滤器：需要 gmail.settings.basic 范围 — 请使用特殊的手动 OAuth 流程（参见 references/api_reference.md）。
• 写入确认：执行 +send、+insert、+email-to-task、+file-announce、drive files delete、events delete、messages trash 前，务必先向用户确认。
• 格式选择：面向用户阅读的摘要使用 --format table；编写脚本或通过管道传递给 jq 时，默认使用 json。

OAuth 设置

• GCP 项目：n8n-automations-454016
• 凭据：~/.config/gws/credentials.json
• 已配置的范围：gmail.modify、gmail.settings.basic、drive、spreadsheets、tasks、calendar、documents、chat.messages、contacts.readonly
• gmail.settings.basic 范围需要手动进行 OAuth（通过 Python 本地主机监听器，使用端口 8085）——gws auth login --scopes 无法直接请求此范围。

完整 API 参考

完整命令列表、所有原始 API 调用、分页、标签、草稿、过滤器和 Admin API，请参阅 references/api_reference.md。