LeoYeAI 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:
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
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，授权流程需要用户在浏览器中完成：
gws auth login
- CLI 输出 OAuth URL
- 将链接发给用户，让用户在浏览器中打开并授权
- 用户将回调页面中的授权码复制回来
- 在 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）等。
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[]，两种写法都要准备好。
# 提取 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：
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 条，避免逐条循环的延迟开销：
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 编码后发送：
# 纯文本
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 下载（同样受相对路径限制）：
# 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
线程 / 回复链
按对话线程查看邮件，避免重复同一封邮件的多个副本：
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"}'
标签管理
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
gws gmail users messages trash --params '{"userId":"me","id":"MSG_ID"}'
gws gmail users messages untrash --params '{"userId":"me","id":"MSG_ID"}'
设置
gws gmail users settings getVacation --params '{"userId":"me"}'
gws gmail users settings sendAs list --params '{"userId":"me"}'
Drive
Drive 支持文件和文件夹的完整生命周期管理。所有 --upload 和 --output 路径仅支持相对路径，必须先 cd 到目标目录。
浏览与搜索
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 参数有效，不受此限制。
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"}'
创建文件夹
gws drive files create --params '{}' --json '{"name":"Folder Name","mimeType":"application/vnd.google-apps.folder"}'
复制与移动
files copy 的 name 参数有效（与 upload 不同），可一步完成：
# 复制（可同时重命名）
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 转换。
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
权限与存储
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，忽略即可。
gws drive files delete --params '{"fileId":"ID"}'
Calendar
Calendar 支持完整的事件 CRUD、日历管理、忙碌查询和权限控制。所有时间参数使用 RFC 3339 格式。
事件管理
# 查询事件
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"}'
忙碌查询与权限
# 查看忙碌/空闲时段
gws calendar freebusy query --json '{"timeMin":"START_DT","timeMax":"END_DT","items":[{"id":"primary"}]}'
# 日历权限
gws calendar acl list --params '{"calendarId":"primary"}'
日历管理
# 创建/删除二级日历
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。
创建与读取
# 创建 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"
编辑单元格
# 更新单元格（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"}'
行列操作
# 删除行
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"}}]}'
格式化
# 单元格背景色
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 实现。
# 创建
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("")'
编辑
# 插入文本（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 实现。
# 创建
gws slides presentations create --json '{"title":"My Slides"}' --params '{}'
# 获取元数据
gws slides presentations get --params '{"presentationId":"ID"}' | jq '{title, slideCount: (.slides | length)}'
编辑
# 创建文本框并插入文本
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。
# 创建空表单
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 和完成状态管理。
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 不需要。
# 个人资料
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 支持课程、学生和作业管理（需要教育账号）。
# 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
快捷工作流命令，适合日常自动化场景：
gws workflow +standup-report # 今日会议 + 待办任务
gws workflow +meeting-prep # 下一个会议准备
gws workflow +weekly-digest # 本周会议 + 未读邮件数
gws workflow +email-to-task --message-id "MSG_ID" # Gmail → Tasks
General
gws schema <service> # 列出该服务所有方法
gws schema <api.method> # 查询具体参数结构
gws <service> <method> --params '{}' --format table # 表格输出（给人类看）
gws <service> <method> --params '{}' --page-all # 自动翻页
不确定参数时先查 schema，不要猜。JSON + jq 是默认输出模式，--format table 仅用于给人类看。