GWS — Google Workspace CLI

Google's official Workspace CLI (@googleworkspace/cli). One tool for Gmail, Drive, Calendar, Sheets, Docs, Tasks, People, Slides, Forms, Meet, Classroom, and more.

GitHub: https://github.com/googleworkspace/cli

Setup

Each session, set these before using gws:

bash
export GOOGLE_WORKSPACE_PROJECT_ID=<your-project-id>
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=~/.config/gws/credentials.json
export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file

First-time setup and authorization: see Prerequisites below.

Prerequisites

1. 安装 gws

bash
npm install -g @googleworkspace/cli

2. GCP Console 配置

前往 Google Cloud Console → APIs & Services → Library，启用以下 API：

| 服务 | API 名称 | |------|----------| | Gmail | Gmail API | | Drive | Google Drive API | | Calendar | Google Calendar API | | Sheets | Google Sheets API | | Docs | Google Docs API | | Tasks | Tasks API | | People | People API | | Slides | Google Slides API | | Forms | Forms API | | Meet | Google Meet API | | Classroom | Google Classroom API |

大部分 API 在 gws auth login 时会自动关联，但 Sheets/Docs/Slides 等可能需要手动启用后才能调用。

重要：启用 API 和 OAuth scope 是两回事。 API 启用决定"能不能调这个服务"，OAuth scope 决定"能做什么操作"，两者都需要。

3. OAuth 授权

gws 是无头 CLI，授权流程需要用户在浏览器中完成：

bash
gws auth login

1. CLI 输出 OAuth URL
2. 将链接发给用户，让用户在浏览器中打开并授权
3. 用户将回调页面中的授权码复制回来
4. 在 CLI 中粘贴授权码，完成认证

凭证保存在 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 指定的路径。gws auth login -s <service> 支持分批授权特定服务，不会覆盖已有 scope。

如果遇到 insufficient authentication scopes 错误，重新运行 gws auth login 并勾选缺少的权限。

Troubleshooting

• insufficient authentication scopes → 见 Prerequisites > Scope 说明，重新授权并勾选缺少的权限
• File not found → 检查是否使用了绝对路径，改用相对路径（见 Usage Philosophy）
• 上传后文件名为 "Untitled" → 用 files update 重命名（见 Known API Quirks）
• 参数不确定 → gws schema <api.method> 查询任意 API 的完整参数结构
• API 未启用 → 见 Prerequisites > GCP Console，启用对应 API

Gmail

Gmail 是最常用的服务，支持完整的邮件 CRUD、搜索、标签、附件、线程、批量操作和设置管理。

每次 gws 调用有 ~2-3s 启动延迟，批量操作优先（batchModify 每批 ≤100 条）。逐条 get 邮件可用 & 并行 + wait 加速。

搜索与列表

Gmail 搜索语法通过 q 参数传递，功能强大：newer_than:1d、is:starred、is:unread、from:xxx、subject:keyword、label:xxx、has:attachment、after:YYYY/MM/DD、before:YYYY/MM/DD、category:primary（primary/promotions/social/updates/forums）等。

bash
gws gmail users messages list --params '{"userId":"me","q":"is:unread","maxResults":20}'
gws gmail users messages list --params '{"userId":"me","q":"is:unread"}' --page-all

读取邮件

messages list 仅返回 ID，需逐条 get。只需要摘要用 format=metadata（更快省 token），需要正文用 format=full。

注意：API 返回的 header 顺序不固定（按内部存储顺序，非请求顺序），必须按 header name 匹配，不能按数组 index 取值。

邮件正文 parts 结构不固定——有些是单层 .payload.parts[]，有些是嵌套 .payload.parts[].parts[]，两种写法都要准备好。

bash
# 提取 headers（按 name 匹配，不要按 index）
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"metadata","metadataHeaders":["From","Subject","Date"]}'
# → jq '.payload.headers | map({(.name): .value}) | add'

# 纯文本正文（先试单层，为空再试嵌套）
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"full"}' | jq -r '.payload.parts[] | select(.mimeType == "text/plain") | .body.data' | base64 -d
# 嵌套备选: jq -r '.payload.parts[].parts[]? | select(.mimeType == "text/plain") | .body.data' | base64 -d

# 快速预览（无需 base64，但有长度限制）
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"metadata"}' | jq -r '.snippet'

并行批量读取

利用 & 后台并行将 N×3s 降到 ~3s：

bash
IDS=$(gws gmail users messages list --params '{"userId":"me","q":"is:unread","maxResults":10}' 2>/dev/null | jq -r '.messages[].id')
for id in $IDS; do
  gws gmail users messages get --params "{\"userId\":\"me\",\"id\":\"$id\",\"format\":\"metadata\",\"metadataHeaders\":[\"From\",\"Subject\",\"Date\"]}" 2>/dev/null | jq -r '.payload.headers | map({(.name): .value}) | add | "\(.From[:30]) | \(.Subject) — \(.Date)"' &
done; wait

批量操作

batchModify 一次处理最多 100 条，避免逐条循环的延迟开销：

bash
IDS=$(gws gmail users messages list --params '{"userId":"me","q":"is:unread","maxResults":100}' 2>/dev/null | jq -c '[.messages[].id]')
gws gmail users messages batchModify --params '{"userId":"me"}' --json "{\"ids\":$IDS,\"removeLabelIds\":[\"UNREAD\"]}"
gws gmail users messages batchModify --params '{"userId":"me"}' --json "{\"ids\":$IDS,\"addLabelIds\":[\"STARRED\"]}"

发送邮件

构造 RFC 2822 格式邮件，Base64 编码后发送：

bash
# 纯文本
RAW=$(printf "To: recipient@example.com\r\nSubject: Hello\r\nFrom: me@gmail.com\r\nContent-Type: text/plain; charset=utf-8\r\n\r\nBody text here" | base64 -w0)
gws gmail users messages send --json "{\"raw\":\"$RAW\"}" --params '{"userId":"me"}'

# HTML（改 Content-Type 为 text/html）
RAW=$(printf "To: recipient@example.com\r\nSubject: Hello\r\nFrom: me@gmail.com\r\nContent-Type: text/html; charset=utf-8\r\n\r\n<h1>Title</h1><p>Body</p>" | base64 -w0)
gws gmail users messages send --json "{\"raw\":\"$RAW\"}" --params '{"userId":"me"}'

附件下载

先从 format=full 响应中提取 attachmentId，再用 attachments get 下载（同样受相对路径限制）：

bash
# 1. 获取附件列表
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"full"}' | jq '[.payload.parts[] | select(.filename != "") | {filename, body: .body.attachmentId}]'

# 2. 下载（cd 到目标目录）
cd /path/to/target/dir
gws gmail users messages attachments get --params '{"userId":"me","messageId":"MSG_ID","id":"ATTACHMENT_ID"}' --output filename.pdf

线程 / 回复链

按对话线程查看邮件，避免重复同一封邮件的多个副本：

bash
gws gmail users threads list --params '{"userId":"me","q":"is:unread","maxResults":10}'
gws gmail users threads get --params '{"userId":"me","id":"THREAD_ID","format":"metadata"}'

标签管理

bash
gws gmail users labels list --params '{"userId":"me"}' | jq '.labels[] | {id, name, type}'
gws gmail users labels create --json '{"name":"Projects/AI","labelListVisibility":"labelShow","messageListVisibility":"show"}' --params '{"userId":"me"}'
gws gmail users messages batchModify --params '{"userId":"me"}' --json '{"ids":["MSG_ID"],"addLabelIds":["LABEL_ID"]}'

Trash

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

设置

bash
gws gmail users settings getVacation --params '{"userId":"me"}'
gws gmail users settings sendAs list --params '{"userId":"me"}'

Drive

Drive 支持文件和文件夹的完整生命周期管理。所有 --upload 和 --output 路径仅支持相对路径，必须先 cd 到目标目录。

浏览与搜索

bash
gws drive files list --params '{"pageSize":10,"orderBy":"modifiedTime desc"}'
gws drive files list --params '{"q":"mimeType=\"application/vnd.google-apps.spreadsheet\""}'
gws drive files list --params '{"q":"'\''FOLDER_ID'\'' in parents"}'

上传（两步命名）

files create 的 name 参数无效（CLI 未传递给 API），上传后文件名始终为 "Untitled"，必须先上传再 rename。注意：files copy 的 name 参数有效，不受此限制。

bash
cd /path/to/target/dir
gws drive files create --params '{}' --upload file.txt --upload-content-type text/plain
gws drive files update --params '{"fileId":"FILE_ID"}' --json '{"name":"real_name.txt"}'

创建文件夹

bash
gws drive files create --params '{}' --json '{"name":"Folder Name","mimeType":"application/vnd.google-apps.folder"}'

复制与移动

files copy 的 name 参数有效（与 upload 不同），可一步完成：

bash
# 复制（可同时重命名）
gws drive files copy --params '{"fileId":"ID"}' --json '{"name":"Copy of file"}'

# 移动到文件夹
gws drive files update --params '{"fileId":"ID","addParents":"FOLDER_ID","removeParents":"root"}' --json '{}'

下载与导出

决策原则：原生文件（txt, pdf, docx 等）用 get --alt media；Google 原生格式（Sheets, Docs, Slides）用 export 转换。

bash
gws drive files get --params '{"fileId":"ID","alt":"media"}' --output file.txt
gws drive files export --params '{"fileId":"ID","mimeType":"application/pdf"}' --output doc.pdf
gws drive files export --params '{"fileId":"ID","mimeType":"text/csv"}' --output data.csv

权限与存储

bash
gws drive permissions list --params '{"fileId":"ID","pageSize":10}'
gws drive about get --params '{"fields":"storageQuota"}' | jq '.storageQuota'

删除

files delete 成功时返回 {"status":"success","saved_file":"download.html"} 而非空 JSON，忽略即可。

bash
gws drive files delete --params '{"fileId":"ID"}'

Calendar

Calendar 支持完整的事件 CRUD、日历管理、忙碌查询和权限控制。所有时间参数使用 RFC 3339 格式。

事件管理

bash
# 查询事件
gws calendar events list --params '{"calendarId":"primary","timeMin":"START_DATETIME","timeMax":"END_DATETIME","maxResults":20}'

# 创建事件
gws calendar events insert --json '{"summary":"Meeting","start":{"dateTime":"DATETIME_START","timeZone":"Asia/Shanghai"},"end":{"dateTime":"DATETIME_END","timeZone":"Asia/Shanghai"}}' --params '{"calendarId":"primary"}'

# 更新/删除事件
gws calendar events update --params '{"calendarId":"primary","eventId":"EVENT_ID"}' --json '{"summary":"Updated"}'
gws calendar events delete --params '{"calendarId":"primary","eventId":"EVENT_ID"}'

# 查看重复事件的所有实例
gws calendar events instances --params '{"calendarId":"primary","eventId":"RECURRING_EVENT_ID"}'

忙碌查询与权限

bash
# 查看忙碌/空闲时段
gws calendar freebusy query --json '{"timeMin":"START_DT","timeMax":"END_DT","items":[{"id":"primary"}]}'

# 日历权限
gws calendar acl list --params '{"calendarId":"primary"}'

日历管理

bash
# 创建/删除二级日历
gws calendar calendars insert --json '{"summary":"My Calendar"}' --params '{}'
gws calendar calendars delete --params '{"calendarId":"CALENDAR_ID"}'

# 日历列表管理
gws calendar calendarList list --params '{"maxResults":10}'

Sheets

Sheets 支持完整的电子表格操作：读写单元格、公式、格式化、行列操作、条件格式、冻结等。

Sheet 名称不一定是 "Sheet1"，+read 的 range 必须用实际 sheet 名，先 get 获取 .sheets[].properties.title。

创建与读取

bash
# 创建 Spreadsheet
gws sheets spreadsheets create --json '{"properties":{"title":"My Sheet"}}' --params '{}'

# 获取 sheet 名称
SHEET=$(gws sheets spreadsheets get --params '{"spreadsheetId":"ID"}' 2>/dev/null | jq -r '.sheets[0].properties.title')

# 读取
gws sheets +read --spreadsheet "ID" --range "${SHEET}!A1:C10"

编辑单元格

bash
# 更新单元格（RAW = 原样写入）
gws sheets spreadsheets values update --params '{"spreadsheetId":"ID","range":"Sheet1!A1","valueInputOption":"RAW"}' --json '{"values":[["New Value"]]}'

# 输入公式（必须用 USER_ENTERED，不能用 RAW）
gws sheets spreadsheets values update --params '{"spreadsheetId":"ID","range":"Sheet1!C1","valueInputOption":"USER_ENTERED"}' --json '{"values":[["=AVERAGE(B2:B10)"]]}'
gws sheets spreadsheets values update --params '{"spreadsheetId":"ID","range":"Sheet1!D1","valueInputOption":"USER_ENTERED"}' --json '{"values":[["=SUM(B2:B10)"]]}'
gws sheets spreadsheets values update --params '{"spreadsheetId":"ID","range":"Sheet1!E1","valueInputOption":"USER_ENTERED"}' --json '{"values":[["=IF(B2>90,\"A\",\"B\")"]]}'

# 追加行（注意：+append 没有 --range 参数，始终追加到第一个 sheet 末尾）
gws sheets +append --spreadsheet "ID" --values 'col1,col2'
gws sheets +append --spreadsheet "ID" --json-values '[["col1","col2"],["col3","col4"]]'

# 清空单元格（保留格式）
gws sheets spreadsheets values clear --params '{"spreadsheetId":"ID","range":"Sheet1!A1:C10"}'

行列操作

bash
# 删除行
gws sheets spreadsheets batchUpdate --params '{"spreadsheetId":"ID"}' --json '{"requests":[{"deleteDimension":{"range":{"sheetId":0,"dimension":"ROWS","startIndex":2,"endIndex":3}}}]}'

# 插入行/列
gws sheets spreadsheets batchUpdate --params '{"spreadsheetId":"ID"}' --json '{"requests":[{"insertDimension":{"range":{"sheetId":0,"dimension":"COLUMNS","startIndex":1,"endIndex":2},"inheritFromBefore":true}}]}'

# 合并单元格
gws sheets spreadsheets batchUpdate --params '{"spreadsheetId":"ID"}' --json '{"requests":[{"mergeCells":{"range":{"sheetId":0,"startRowIndex":0,"endRowIndex":1,"startColumnIndex":0,"endColumnIndex":3},"mergeType":"MERGE_ALL"}}]}'

# 设置列宽/行高
gws sheets spreadsheets batchUpdate --params '{"spreadsheetId":"ID"}' --json '{"requests":[{"updateDimensionProperties":{"range":{"sheetId":0,"dimension":"COLUMNS","startIndex":0,"endIndex":1},"properties":{"pixelSize":200},"fields":"pixelSize"}}]}'

格式化

bash
# 单元格背景色
gws sheets spreadsheets batchUpdate --params '{"spreadsheetId":"ID"}' --json '{"requests":[{"repeatCell":{"range":{"sheetId":0,"startRowIndex":0,"endRowIndex":1},"cell":{"userEnteredFormat":{"backgroundColor":{"red":0.2,"green":0.6,"blue":1}},"fields":"userEnteredFormat.backgroundColor"}}}]}'

# 条件格式
gws sheets spreadsheets batchUpdate --params '{"spreadsheetId":"ID"}' --json '{"requests":[{"addConditionalFormatRule":{"rule":{"ranges":[{"sheetId":0,"startRowIndex":1,"endRowIndex":100}],"booleanRule":{"condition":{"type":"NUMBER_GREATER","values":[{"userEnteredValue":"90"}]},"format":{"backgroundColor":{"red":0,"green":1,"blue":0}}}},"index":0}}]}'

# 冻结行/列
gws sheets spreadsheets batchUpdate --params '{"spreadsheetId":"ID"}' --json '{"requests":[{"updateSheetProperties":{"properties":{"sheetId":0,"gridProperties":{"frozenRowCount":1,"frozenColumnCount":1}},"fields":"gridProperties.frozenRowCount,gridProperties.frozenColumnCount"}}]}'

Docs

Docs 支持创建、读取、编辑文档。文档编辑通过 batchUpdate 实现。

bash
# 创建
gws docs documents create --json '{"title":"My Doc"}' --params '{}'

# 提取纯文本
gws docs documents get --params '{"documentId":"ID"}' | jq '[.body.content[]|select(.paragraph)|.paragraph.elements[]?|select(.textRun)|.textRun.content]|join("")'

编辑

bash
# 插入文本（index 1 = 文档开头）
gws docs documents batchUpdate --json '{"requests":[{"insertText":{"location":{"index":1},"text":"Hello World\n"}}]}' --params '{"documentId":"ID"}'

# 设置文本样式（加粗、斜体、字号、颜色等）
gws docs documents batchUpdate --json '{"requests":[{"updateTextStyle":{"range":{"startIndex":1,"endIndex":6},"textStyle":{"bold":true},"fields":"bold"}}]}' --params '{"documentId":"ID"}'

# 设置段落样式（标题、列表等）
gws docs documents batchUpdate --json '{"requests":[{"updateParagraphStyle":{"range":{"startIndex":1,"endIndex":10},"style":{"namedStyleType":"HEADING_1"},"fields":"namedStyleType"}}]}' --params '{"documentId":"ID"}'

# 插入图片
gws docs documents batchUpdate --json '{"requests":[{"insertInlineImage":{"uri":"https://example.com/image.png","location":{"index":1}}}]} --params '{"documentId":"ID"}'

# 创建列表（bullet）
gws docs documents batchUpdate --json '{"requests":[{"createParagraphBullets":{"range":{"startIndex":1,"endIndex":20},"bulletPreset":"BULLET_DISC_CIRCLE_SQUARE"}}]}' --params '{"documentId":"ID"}'

Slides

Slides 支持创建、读取、编辑演示文稿。编辑通过 batchUpdate 实现。

bash
# 创建
gws slides presentations create --json '{"title":"My Slides"}' --params '{}'

# 获取元数据
gws slides presentations get --params '{"presentationId":"ID"}' | jq '{title, slideCount: (.slides | length)}'

编辑

bash
# 创建文本框并插入文本
gws slides presentations batchUpdate --json '{"requests":[{"createShape":{"objectId":"shape1","shapeType":"TEXT_BOX","elementProperties":{"pageObjectId":"p1","size":{"width":{"magnitude":4000000,"unit":"EMU"},"height":{"magnitude":300000,"unit":"EMU"}},"transform":{"scaleX":1,"scaleY":1,"translateX":100000,"translateY":100000,"unit":"EMU"}}}},{"insertText":{"objectId":"shape1","text":"Hello Slides!"}}]}' --params '{"presentationId":"ID"}'

# 设置文本样式（加粗 + 字号）
gws slides presentations batchUpdate --json '{"requests":[{"updateTextStyle":{"objectId":"shape1","style":{"bold":true,"fontSize":{"magnitude":36,"unit":"PT"}},"textRange":{"type":"ALL"},"fields":"bold,fontSize"}}]}' --params '{"presentationId":"ID"}'

# 新增幻灯片
gws slides presentations batchUpdate --json '{"requests":[{"createSlide":{"objectId":"slide2"}}]}' --params '{"presentationId":"ID"}'

# 插入图片
gws slides presentations batchUpdate --json '{"requests":[{"createImage":{"url":"https://example.com/image.png","elementProperties":{"pageObjectId":"p1","size":{"width":{"magnitude":3000000,"unit":"EMU"},"height":{"magnitude":2000000,"unit":"EMU"}},"transform":{"scaleX":1,"scaleY":1,"translateX":500000,"translateY":500000,"unit":"EMU"}}}}]}' --params '{"presentationId":"ID"}'

> 注意：presentations create 输出的是完整对象，提取 presentationId 需要解析 JSON。Slides 坐标单位为 EMU（1 inch = 914400 EMU）。

Forms

Forms 支持创建表单、添加题目和查看回复。forms create 只能创建空表单（仅 title 生效），添加题目需要用 batchUpdate。

bash
# 创建空表单
gws forms forms create --json '{"info":{"title":"Survey"}}' --params '{}'

# 添加文本题目（location 是必填字段，放在 createItem 级别）
gws forms forms batchUpdate --json '{"requests":[{"createItem":{"location":{"index":0},"item":{"title":"What is your name?","questionItem":{"question":{"required":true,"textQuestion":{}}}}}}]}' --params '{"formId":"FORM_ID"}'

# 查看回复
gws forms forms responses list --params '{"formId":"FORM_ID"}'

Tasks

Tasks 支持任务列表 CRUD 和完成状态管理。

bash
gws tasks tasklists list | jq '.items[]|{title,id}'
gws tasks tasks list --params '{"tasklist":"@default"}' | jq '.items[]|{title,status,due}'
gws tasks tasks insert --json '{"title":"Task","notes":"Details"}' --params '{"tasklist":"@default"}'
gws tasks tasks patch --params '{"tasklist":"@default","task":"TASK_ID"}' --json '{"status":"completed"}'
gws tasks tasks delete --params '{"tasklist":"@default","task":"TASK_ID"}'
gws tasks tasks clear --params '{"tasklist":"@default"}'  # 清除所有已完成任务

People

People 支持个人资料、联系人搜索/创建和分组管理。searchContacts 必须指定 readMask，不传会报 400。connections list 不需要。

bash
# 个人资料
gws people people get --params '{"resourceName":"people/me","personFields":"names,emailAddresses"}'

# 搜索联系人（必须指定 readMask）
gws people people searchContacts --params '{"query":"keyword","pageSize":10,"readMask":"names,emailAddresses,phoneNumbers"}'

# 联系人列表
gws people connections list --params '{"resourceName":"people/me","personFields":"names,emailAddresses,phoneNumbers","pageSize":10}'

# 创建联系人
gws people people createContact --json '{"names":[{"givenName":"First","familyName":"Last"}],"emailAddresses":[{"value":"email@example.com"}]}' --params '{"readMask":"names,emailAddresses"}'

# 联系人分组
gws people contactGroups list --params '{"pageSize":10}'

Meet / Classroom

Meet 支持会议记录查询。Classroom 支持课程、学生和作业管理（需要教育账号）。

bash
# Meet: 会议记录
gws meet conferenceRecords list --params '{"pageSize":10}'
gws meet conferenceRecords get --params '{"name":"RECORD_ID"}'

# Classroom: 课程、学生、作业
gws classroom courses list --params '{"pageSize":10}'
gws classroom courses students list --params '{"courseId":"COURSE_ID"}'
gws classroom courses.courseWork list --params '{"courseId":"COURSE_ID"}'

Workflow Helpers

快捷工作流命令，适合日常自动化场景：

bash
gws workflow +standup-report        # 今日会议 + 待办任务
gws workflow +meeting-prep          # 下一个会议准备
gws workflow +weekly-digest         # 本周会议 + 未读邮件数
gws workflow +email-to-task --message-id "MSG_ID"  # Gmail → Tasks

General

bash
gws schema <service>              # 列出该服务所有方法
gws schema <api.method>           # 查询具体参数结构
gws <service> <method> --params '{}' --format table   # 表格输出（给人类看）
gws <service> <method> --params '{}' --page-all       # 自动翻页

不确定参数时先查 schema，不要猜。JSON + jq 是默认输出模式，--format table 仅用于给人类看。