Back to Details

gws

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google Workspace CLI (gws)

Google Workspace CLI（gws）

CLI for Gmail, Calendar, Drive, Sheets, Docs, Slides, Tasks, People, Chat, Meet, Forms, Keep, Admin, and cross-service workflows.
Binary: 
/opt/homebrew/bin/gws
用于Gmail、Calendar、Drive、Sheets、Docs、Slides、Tasks、People、Chat、Meet、Forms、Keep、Admin以及跨服务工作流的CLI工具。
二进制文件路径：
/opt/homebrew/bin/gws

Command Pattern

命令格式

gws <service> <resource> [sub-resource] <method> [flags]
Every command accepts:
  • --params <JSON>
    — URL/query parameters
  • --json <JSON>
    — request body (POST/PATCH/PUT)
  • --upload <PATH>
    — file to upload as media content
  • --output <PATH>
    — path for binary responses (downloads)
  • --format json|table|yaml|csv
    — output format (default: json)
  • --page-all
    / 
    --page-limit N
    — auto-paginate
  • --dry-run
    — validate locally without sending
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
    — 仅本地验证，不发送请求

Quick Reference — Helper Commands (prefer these)

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

CommandPurposeR/W
gws gmail +triage [--max N] [--query Q]
Unread inbox summaryR
gws gmail +send --to EMAIL --subject S --body T
Send plaintext emailW
gws gmail +watch --project GCP
Stream new emails (Pub/Sub)R
gws calendar +agenda [--today|--tomorrow|--week|--days N]
Upcoming eventsR
gws calendar +insert --summary T --start ISO --end ISO
Create eventW
gws drive +upload FILE [--parent ID] [--name N]
Upload fileW
gws sheets +read --spreadsheet ID --range R
Read range (e.g. 
Sheet1!A1:D10
)		R
gws sheets +append --spreadsheet ID --values "a,b,c"
Append row (or 
--json-values
)		W
gws docs +write --document ID --text T
Append text to docW
gws chat +send --space spaces/ID --text T
Post to Chat spaceW
gws workflow +standup-report
Today's meetings + open tasksR
gws workflow +meeting-prep [--calendar ID]
Next meeting detailsR
gws workflow +email-to-task --message-id ID
Email → TaskW
gws workflow +weekly-digest
Week's meetings + unreadR
gws workflow +file-announce --file-id ID --space SPACE
Announce file in ChatW
命令用途读/写
gws gmail +triage [--max N] [--query Q]
未读收件箱摘要读
gws gmail +send --to EMAIL --subject S --body T
发送纯文本邮件写
gws gmail +watch --project GCP
流式接收新邮件（Pub/Sub）读
gws calendar +agenda [--today|--tomorrow|--week|--days N]
即将到来的事件读
gws calendar +insert --summary T --start ISO --end ISO
创建事件写
gws drive +upload FILE [--parent ID] [--name N]
上传文件写
gws sheets +read --spreadsheet ID --range R
读取指定范围（例如 
Sheet1!A1:D10
）		读
gws sheets +append --spreadsheet ID --values "a,b,c"
追加行（或使用 
--json-values
）		写
gws docs +write --document ID --text T
向文档追加文本写
gws chat +send --space spaces/ID --text T
发送消息到Chat空间写
gws workflow +standup-report
今日会议+待办任务读
gws workflow +meeting-prep [--calendar ID]
下一场会议详情读
gws workflow +email-to-task --message-id ID
邮件转任务写
gws workflow +weekly-digest
本周会议+未读邮件读
gws workflow +file-announce --file-id ID --space SPACE
在Chat中分享文件通知写

Common Patterns

常用命令示例

Gmail

Gmail

bash
undefined
bash
undefined

Triage unread (table for humans)

分类处理未读邮件（表格格式便于阅读）

gws gmail +triage --max 10 --format table
gws gmail +triage --max 10 --format table

Search

搜索邮件

gws gmail users messages list --params '{"userId":"me","q":"from:amazon newer_than:7d","maxResults":5}'
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"}'
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"]}'
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"metadata","metadataHeaders":["Subject","From","Date"]}'

Archive (remove INBOX)

归档邮件（移除INBOX标签）

gws gmail users messages modify --params '{"userId":"me","id":"MSG_ID"}' --json '{"removeLabelIds":["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"}'
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"]}'
undefined
gws gmail users messages batchModify --params '{"userId":"me"}' --json '{"ids":["ID1","ID2"],"addLabelIds":["Label_123"]}'
undefined

Calendar

Calendar

bash
undefined
bash
undefined

Today (Europe/Berlin default works with RFC3339 +02:00/+01:00)

查看今日日程（默认使用Europe/Berlin时区，兼容RFC3339格式的+02:00/+01:00偏移）

gws calendar +agenda --today --format table
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'
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)

创建带Google Meet链接的事件（辅助命令不支持，需使用原生命令）

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"}}} }'
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"}'
gws calendar events patch --params '{"calendarId":"primary","eventId":"EID"}' --json '{"summary":"New title"}'

Delete

删除事件

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

List all calendars

列出所有日历

gws calendar calendarList list --format table
undefined
gws calendar calendarList list --format table
undefined

Drive

Drive

bash
undefined
bash
undefined

Upload to root

上传文件到根目录

gws drive +upload ./report.pdf
gws drive +upload ./report.pdf

Upload to folder

上传文件到指定文件夹

gws drive +upload ./data.csv --parent FOLDER_ID --name 'Sales Data.csv'
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}'
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
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"}'
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":"user@example.com"}'
undefined
gws drive permissions create --params '{"fileId":"FID"}' --json '{"role":"reader","type":"user","emailAddress":"user@example.com"}'
undefined

Sheets

Sheets

bash
undefined
bash
undefined

Read

读取表格内容

gws sheets +read --spreadsheet SID --range 'Sheet1!A1:D10' --format table
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'
gws sheets +append --spreadsheet SID --values 'Alice,100,true'

Append multiple rows

追加多行数据

gws sheets +append --spreadsheet SID --json-values '[["a","b"],["c","d"]]'
undefined
gws sheets +append --spreadsheet SID --json-values '[["a","b"],["c","d"]]'
undefined

Tasks

Tasks

bash
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"}'
bash
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

Chat

bash
undefined
bash
undefined

Find space

查找Chat空间

gws chat spaces list --format table
gws chat spaces list --format table

Post message

发送消息

gws chat +send --space spaces/AAAAxxxx --text 'Hello team!'
undefined
gws chat +send --space spaces/AAAAxxxx --text 'Hello team!'
undefined

People / Contacts

People / 联系人

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

Critical Notes

重要注意事项

  • userId: Every Gmail raw call needs 
    "userId":"me"
    in params.
  • RFC3339 times: Calendar uses full ISO with offset (
    2026-04-14T18:00:00+02:00
    ). "Z" for UTC.
  • Meet links: 
    +insert
    does NOT add conferencing — use raw 
    events.insert
    with 
    conferenceDataVersion=1
    and 
    conferenceData.createRequest
    .
  • Pagination: 
    --page-all
    emits NDJSON (one JSON object per page). 
    --page-limit N
    caps pages.
  • Schema discovery: 
    gws schema <service>.<resource>.<method>
    — e.g. 
    gws schema gmail.users.messages.list
    .
  • Filters: 
    gmail.settings.basic
    scope required — special manual OAuth flow (see 
    references/api_reference.md
    ).
  • Write confirmation: Always confirm with user before 
    +send
    , 
    +insert
    , 
    +email-to-task
    , 
    +file-announce
    , 
    drive files delete
    , 
    events delete
    , 
    messages trash
    .
  • Format choice: 
    --format table
    for human-readable summaries; default 
    json
    for scripting/piping to 
    jq
    .
  • userId：所有Gmail原生调用都需要在参数中包含
    "userId":"me"
    。
  • RFC3339时间格式：Calendar使用带时区偏移的完整ISO格式（如
    2026-04-14T18:00:00+02:00
    ），使用"Z"表示UTC时区。
  • Meet链接：
    +insert
    命令不支持添加会议链接——需使用原生
    events.insert
    命令，并指定
    conferenceDataVersion=1
    和
    conferenceData.createRequest
    参数。
  • 分页：
    --page-all
    参数会输出NDJSON格式（每页一个JSON对象）；
    --page-limit N
    参数用于限制分页数量。
  • Schema发现：使用
    gws schema <service>.<resource>.<method>
    命令查看接口Schema——例如
    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
    用于生成便于人类阅读的摘要；默认的
    json
    格式适用于脚本编写或通过
    jq
    工具处理。

OAuth Setup

OAuth配置

  • GCP project: 
    n8n-automations-454016
  • Credentials: 
    ~/.config/gws/credentials.json
  • Configured scopes: 
    gmail.modify
    , 
    gmail.settings.basic
    , 
    drive
    , 
    spreadsheets
    , 
    tasks
    , 
    calendar
    , 
    documents
    , 
    chat.messages
    , 
    contacts.readonly
  • gmail.settings.basic
    scope needs manual OAuth (Python localhost listener on port 8085) — 
    gws auth login --scopes
    cannot request it directly.
  • 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
    命令无法直接申请该权限。

Full API Reference

完整API参考

For full command inventory, all raw API calls, pagination, labels, drafts, filters, and admin APIs, see 
references/api_reference.md
.
如需查看完整命令清单、所有原生API调用、分页、标签、草稿、过滤器及管理员API，请参考
references/api_reference.md
。