googleworkspace--cli/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

gws

一个 CLI，统驭全部 Google Workspace — 为人与 AI 智能体而生。
Drive、Gmail、Calendar 及全部 Workspace API。零样板代码。结构化 JSON 输出。内置 40+ 个 agent skills。

Note

这不是 Google 官方支持的产品。

⬇️ 下载适用于你操作系统的最新版本

gws 不提供静态命令列表。它会在运行时读取 Google 自有的 Discovery Service，并动态构建整套命令界面。当 Google Workspace 新增 API 端点或方法时，gws 会自动吸纳。

Important

本项目仍在积极开发中。在向 v1.0 推进的过程中，预计会出现破坏性变更。

目录

• 前置要求
• 安装
• 快速开始
• 为什么选择 gws？
• 身份验证
• AI Agent Skills
• 高级用法
• 环境变量
• 退出码
• 架构
• 故障排除
• 开发

前置要求

• Node.js 18+ — 用于 npm install（或从 GitHub Releases) 下载预编译二进制文件
• Google Cloud 项目 — OAuth 凭据所需。可通过 Google Cloud Console 创建，或使用 gcloud CLI，或使用 gws auth setup 命令。
• 拥有 Google Workspace 访问权限的 Google 账号

安装

推荐安装 gws 的方式是：从 GitHub Releases 页面下载适用于你操作系统和架构的预编译二进制文件。解压归档文件，并将 gws 二进制文件放入 $PATH。

为方便起见，也可使用 npm 自动从 GitHub Releases 下载对应二进制文件：

npm install -g @googleworkspace/cli

或从源码构建：

cargo install --git https://github.com/googleworkspace/cli --locked

Nix flake 也可在 github:googleworkspace/cli 获取

nix run github:googleworkspace/cli

在 macOS 和 Linux 上，也可通过 Homebrew: 安装

brew install googleworkspace-cli

快速开始

gws auth setup     # walks you through Google Cloud project config
gws auth login     # subsequent OAuth login
gws drive files list --params '{"pageSize": 5}'

为什么选择 gws？

面向人类 — 别再对着 REST 文档手写 curl 调用。gws 为每个资源提供 --help、用于预览请求的 --dry-run，以及自动分页。

面向 AI 智能体 — 每个响应均为结构化 JSON。配合内置的 agent skills，你的 LLM 即可管理 Workspace，无需自定义工具链。

# List the 10 most recent files
gws drive files list --params '{"pageSize": 10}'

# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Send a Chat message
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# Introspect any method's request/response schema
gws schema drive.files.list

# Stream paginated results as NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

身份验证

该 CLI 支持多种身份验证流程，可在笔记本电脑、CI 和服务器上运行。

我该用哪种配置？

我已有…	使用
已安装并完成身份验证的 gcloud	gws auth setup（最快）
有 GCP 项目但没有 gcloud	手动 OAuth 配置
已有的 OAuth 访问令牌	GOOGLE_WORKSPACE_CLI_TOKEN
已有凭据	GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE

交互式（本地桌面）

凭据静态加密存储（AES-256-GCM），密钥保存在系统密钥环（或当 GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file 时的 ~/.config/gws/.encryption_key）中。

gws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in
gws auth login       # subsequent scope selection and login

gws auth setup 需要 gcloud CLI.。若没有 gcloud，请改用下方的 手动配置。

Warning

测试模式下的 Scope 限制： 若 OAuth 应用未经验证（测试模式），Google 将同意范围限制在约 25 个 scope。recommended scope 预设包含 85+ 个 scope，对未验证应用将失败（对 @gmail.com 账号尤为明显）。请改为选择单个服务以筛选 scope 选择器：

gws auth login -s drive,gmail,sheets

手动 OAuth 配置（Google Cloud Console）

当 gws auth setup 无法自动创建项目/客户端，或你需要显式控制时使用此方式。

1. 在目标项目中打开 Google Cloud Console：
   • OAuth 同意屏幕：https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>
   • 凭据：https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>
2. 若提示，配置 OAuth 品牌/受众：
   • 应用类型：External（测试模式即可）
3. 在 Test users 下添加你的账号
4. 创建 OAuth 客户端：
   • 类型：Desktop app
5. 下载客户端 JSON 并保存至：
   • ~/.config/gws/client_secret.json

Important

你必须将自己添加为测试用户。 在 OAuth 同意屏幕上，点击 Test users → Add users，输入你的 Google 账号邮箱。否则登录将因笼统的「Access blocked」错误而失败。

然后运行：

gws auth login

浏览器辅助身份验证（人类或智能体）

你可以手动完成 OAuth，也可借助浏览器自动化完成。

• 人类流程：运行 gws auth login，打开打印出的 URL，批准 scope。
• 智能体辅助流程：智能体打开 URL、选择账号、处理同意提示，并在 localhost 回调成功后交还控制权。

若同意页面显示 "Google hasn't verified this app"（测试模式），点击 Continue。 若出现 scope 复选框，请先选择所需 scope（或 Select all）再继续。

无头 / CI（导出流程）

1. 在带浏览器的机器上完成交互式身份验证。
2. 导出凭据：

   gws auth export --unmasked > credentials.json
   

3. 在无头机器上：

   export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
   gws drive files list   # just works
   

服务账号（server-to-server）

指向你的密钥文件；无需登录。

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

预先获取的访问令牌（Pre-obtained Access Token）

当其他工具（例如 gcloud）已为你的环境签发令牌时很有用。

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

优先级

优先级	来源	设置方式
1	访问令牌	GOOGLE_WORKSPACE_CLI_TOKEN
2	凭据文件	GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
3	加密凭据	gws auth login
4	明文凭据	~/.config/gws/credentials.json

环境变量也可以放在 .env 文件中。

AI Agent Skills

本仓库提供 100+ 个 Agent Skills（SKILL.md 文件）——每个受支持的 API 各有一个，此外还有面向常见工作流的高层辅助技能，以及 50 个针对 Gmail、Drive、Docs、Calendar 和 Sheets 的精选配方。完整列表见 Skills Index。

# Install all skills at once
npx skills add https://github.com/googleworkspace/cli

# Or pick only what you need
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

OpenClaw 设置

# Symlink all skills (stays in sync with repo)
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

# Or copy specific skills
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

gws-shared 技能包含一个 install 代码块，这样当 gws 不在 PATH 上时，OpenClaw 会通过 npm 自动安装 CLI。

Gemini CLI Extension

1. 首先对 CLI 进行身份验证：

   gws auth setup
   

2. 将扩展安装到 Gemini CLI：

   gemini extensions install https://github.com/googleworkspace/cli
   

安装此扩展后，你的 Gemini CLI agent 可直接使用所有 gws 命令和 Google Workspace agent skills。由于 gws 会安全地自行处理身份验证，你只需在使用 agent 前对终端完成一次身份验证，扩展会自动继承你的凭据。

Advanced Usage

Multipart Uploads

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

Pagination

Flag	Description	Default
--page-all	自动分页，每页一行 JSON（NDJSON）	off
--page-limit <N>	最多获取的页数	10
--page-delay <MS>	分页之间的延迟	100 ms

Google Sheets — Shell Escaping

Sheets 范围使用 !，bash 会将其解释为历史展开。请始终用单引号包裹值：

# Read cells A1:C10 from "Sheet1"
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

# Append rows
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

Helper Commands

部分服务在自动生成的 Discovery 接口之外，还提供手工编写的辅助命令。辅助命令以 + 为前缀，以便与 Discovery 生成的方法名在视觉上区分，且不会发生冲突。

感知时间的辅助命令（+agenda、+standup-report、+weekly-digest、+meeting-prep）会自动使用你的 Google 账户时区（从 Calendar Settings API 获取并缓存 24 小时）。可在 +agenda 上用 --timezone/--tz 覆盖，或设置 --timezone 标志进行显式控制。

运行 gws <service> --help 可同时查看 Discovery 方法和辅助命令。

gws gmail --help      # shows +send, +reply, +reply-all, +forward, +triage, +watch …
gws calendar --help   # shows +insert, +agenda …
gws drive --help      # shows +upload …

完整辅助命令参考：

Service	Command	Description
gmail	+send	发送邮件
gmail	+reply	回复邮件（自动处理线程）
gmail	+reply-all	回复全部收件人
gmail	+forward	将邮件转发给新收件人
gmail	+triage	显示未读收件箱摘要（发件人、主题、日期）
gmail	+watch	监听新邮件并以 NDJSON 流式输出
sheets	+append	向电子表格追加一行
sheets	+read	从电子表格读取值
docs	+write	向文档追加文本
chat	+send	向空间发送消息
drive	+upload	上传文件并自动生成元数据
calendar	+insert	创建新事件
calendar	+agenda	显示即将到来的事件（使用 Google 账户时区；可用 --timezone 覆盖）
script	+push	用本地文件替换 Apps Script 项目中的所有文件
workflow	+standup-report	今日会议与待办任务，生成站会摘要
workflow	+meeting-prep	为下一场会议做准备：议程、与会者和关联文档
workflow	+email-to-task	将 Gmail 邮件转换为 Google Tasks 条目
workflow	+weekly-digest	周度摘要：本周会议与未读邮件数量
workflow	+file-announce	在 Chat 空间中公告 Drive 文件
events	+subscribe	订阅 Workspace 事件并以 NDJSON 流式输出
events	+renew	续订/重新激活 Workspace Events 订阅
modelarmor	+sanitize-prompt	通过 Model Armor 模板清理用户提示词
modelarmor	+sanitize-response	通过 Model Armor 模板清理模型响应
modelarmor	+create-template	创建新的 Model Armor 模板

示例：

# Send an email
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"

# Reply to a message
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# Append a row to a spreadsheet
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"

# Show today's calendar agenda
gws calendar +agenda

# Upload a file to Drive
gws drive +upload ./report.pdf --name "Q1 Report"

# Morning standup summary
gws workflow +standup-report

# Show today's agenda in a specific timezone
gws calendar +agenda --today --timezone America/New_York

Model Armor (Response Sanitization)

集成 Google Cloud Model Armor，在 API 响应到达你的 agent 之前扫描其中的提示词注入。

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

Variable	Description
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE	默认 Model Armor 模板
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE	warn（默认）或 block

Environment Variables

所有变量均为可选。可复制粘贴模板见 .env.example。

Variable	Description
GOOGLE_WORKSPACE_CLI_TOKEN	预获取的 OAuth2 访问令牌（优先级最高）
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE	OAuth 凭据 JSON 的路径（用户或服务账号）
GOOGLE_WORKSPACE_CLI_CLIENT_ID	OAuth 客户端 ID（client_secret.json 的替代方案）
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET	OAuth 客户端密钥（与 CLIENT_ID 配对）
GOOGLE_WORKSPACE_CLI_CONFIG_DIR	覆盖配置目录（默认：~/.config/gws）
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE	默认 Model Armor 模板
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE	warn（默认）或 block
GOOGLE_WORKSPACE_CLI_LOG	stderr 日志级别（例如 gws=debug）。默认关闭。
GOOGLE_WORKSPACE_CLI_LOG_FILE	带按日轮转的 JSON 日志文件目录。默认关闭。
GOOGLE_WORKSPACE_PROJECT_ID	用于配额/计费的 GCP 项目 ID 覆盖，以及辅助命令的回退值

环境变量也可以设置在 .env 文件中（通过 dotenvy). 加载

Exit Codes

gws 使用结构化退出码，脚本可根据失败类型分支处理，而无需解析错误输出。

Code	Meaning	Example cause
0	成功	命令正常完成
1	API 错误	Google 返回了 4xx/5xx 响应
2	身份验证错误	凭据缺失、过期或无效
3	验证错误	参数错误、未知服务、无效标志
4	Discovery 错误	无法获取 API 架构文档
5	内部错误	意外失败

gws drive files list --params '{"fileId": "bad"}'
echo $?   # 1 — API error

gws unknown-service files list
echo $?   # 3 — validation error (unknown service)

架构

gws 采用 两阶段解析（two-phase parsing）策略：

1. 读取 argv[1] 以识别服务（例如 drive）
2. 获取该服务的 Discovery Document（缓存 24 小时）
3. 根据文档中的资源和 method 构建 clap::Command 树
4. 重新解析剩余参数
5. 完成认证、构建 HTTP 请求并执行

所有输出——成功结果、错误、下载元数据——均为结构化 JSON。

故障排查

登录时出现「Access blocked」或 403

你的 OAuth 应用处于 测试模式（testing mode），且你的账号未列为测试用户。

修复： 在你的 GCP 项目中打开 OAuth consent screen → Test users → Add users → 输入你的 Google 账号邮箱。然后重试 gws auth login。

「Google hasn't verified this app」

应用在测试模式时出现此提示属正常现象。点击 Advanced → Go to <app name> (unsafe) 继续。个人使用是安全的；只有向其他用户公开发布应用时才需要完成验证。

作用域过多 / 同意屏幕错误

未验证（测试模式）应用最多约 25 个 OAuth scope。recommended 的 scope 预设包含大量 scope，会超出此限制。

修复： 仅选择你需要的 scope：

gws auth login --scopes drive,gmail,calendar

找不到 gcloud CLI

gws auth setup 需要 gcloud CLI 来自动创建项目。你有三种选择：

1. Install gcloud，并直接使用 gcloud。
2. 重新运行 gws auth setup，它会封装 gcloud 调用。
3. 完全跳过 gcloud——在 Cloud Console 中手动配置 OAuth 凭据

redirect_uri_mismatch

OAuth 客户端未创建为 Desktop app 类型。在 Credentials 页面，删除现有客户端，新建类型为 Desktop app 的客户端，并下载新的 JSON。

API 未启用 — accessNotConfigured

如果 GCP 项目未启用所需的 Google API，你会看到 reason 为 accessNotConfigured 的 403 错误：

{
  "error": {
    "code": 403,
    "message": "Gmail API has not been used in project 549352339482 ...",
    "reason": "accessNotConfigured",
    "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482"
  }
}

gws 还会在 stderr 上打印一条可操作的提示：

💡 API not enabled for your GCP project.
   Enable it at: https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482
   After enabling, wait a few seconds and retry your command.

修复步骤：

1. 点击 enable_url 链接（或从 enable_url JSON 字段复制）。
2. 在 GCP Console 中点击 Enable。
3. 等待约 10 秒，然后重试 gws 命令。

Tip

你也可以运行 gws auth setup，它会引导你自动为项目启用所有必需的 API。

开发

cargo build                       # dev build
cargo clippy -- -D warnings       # lint
cargo test                        # unit tests
./scripts/coverage.sh             # HTML coverage report → target/llvm-cov/html/

许可证

Apache-2.0

免责声明

Caution

这 并非 Google 官方支持的产品。