gws

这是什么

gws 是一个面向 Google Workspace 的统一命令行工具, 目标是把 Drive, Gmail, Calendar, Sheets, Chat 等所有 Workspace API, 用同一种 CLI 方式调用出来, 并且默认输出结构化 JSON, 方便脚本处理与 AI agent 接管。

它的关键特性是, 命令面是运行时根据 Google Discovery Service 动态生成的, 所以它不会像传统 CLI 那样在仓库里写死一份完整子命令列表。Google 新增 API 或方法后, gws 理论上可以自动跟进。

安装与版本

npm 安装

npm install -g @googleworkspace/cli

说明, npm 包带了预编译二进制, 通常不需要 Rust 工具链。

其他安装方式

• GitHub Releases 下载二进制
• 从源码安装

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

• Nix

  nix run github:googleworkspace/cli
  

基础使用模型

gws 的调用基本形态是

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

例如

gws drive files list --params '{"pageSize": 10}'

因为命令是动态生成的, 所以你在某个 API 下可用的 resource 和 method 需要用 --help 去探索。

常见探索路径

gws --help
# 进入某个 service
gws drive --help
# 进入某个 resource
gws drive files --help
# 看具体 method 的参数
gws drive files list --help

输出与输入

输出

• 默认输出结构化 JSON
• 分页场景下可输出 NDJSON, 便于管道处理

输入

常用两类输入字段

1. --params 传 URL query 参数或路径参数, 典型是 list, get 这种方法
2. --json 传 request body, 典型是 create, update, batch 这种方法

示例

# 创建一个 spreadsheet
gws sheets spreadsheets create \
  --json '{"properties": {"title": "Q1 Budget"}}'

# 发一条 Chat 消息, 并用 dry run 预览
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

认证体系

gws 支持多种认证来源, 兼顾本机交互, CI, 服务器。

交互式本机认证

gws auth setup
gws auth login

要点

• auth setup 依赖 gcloud 来自动创建或配置 GCP 项目, 启用 API 等
• 凭据会加密存储, 密钥放在系统 keyring
• OAuth 在 testing mode 时, scope 数量有上限, 选太多会失败, 这种情况下建议只选需要的服务 scopes

例子

gws auth login -s drive,gmail,sheets

手动 OAuth 配置

适用场景

• 没装 gcloud
• 想完全掌控 GCP 项目与 OAuth 客户端

核心步骤

• 在 GCP Console 创建 Desktop app 类型 OAuth client
• 下载 client JSON, 保存到 ~/.config/gws/client_secret.json
• 确保把自己的账号加到 Test users
• 然后 gws auth login

Headless 或 CI

思路是先在有浏览器的机器完成登录, 然后导出 credentials, 在 CI 上用环境变量引用。

# 交互机器
gws auth export --unmasked > credentials.json

# CI 机器
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

Service Account

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json

外部已有 Access Token

当你已经用别的系统拿到 token, 让 gws 直接复用。

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 明文凭据

重要命令与功能清单

说明, 完整命令面会随 Discovery 动态变化, 下面列的是仓库 README 明确提供的稳定功能点与子命令, 以及你用得上的探索方式。

通用

• gws --help, gws <service> --help, gws <service> <resource> <method> --help
• --dry-run 预览请求, 不真正发送

schema

• gws schema <fully.qualified.method>

用途

• 查看某个 API 方法的请求与响应 schema, 便于快速拼 --params 和 --json

例子

gws schema drive.files.list

auth

• gws auth setup 通过 gcloud 引导配置项目与 API
• gws auth login OAuth 登录, 选择 scopes
• gws auth export --unmasked 导出 credentials, 给 headless 使用

分页

相关参数

• --page-all 自动翻页, 每页一行 JSON, 适合管道
• --page-limit <N> 最大页数, 默认 10
• --page-delay <MS> 页间延迟, 默认 100ms

例子

# 把所有页面输出为 NDJSON, 再用 jq 抽字段
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

上传

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

Sheets 的感叹号

Sheets range 里有 !, 在某些 shell 下会触发历史展开, 处理原则是, JSON 用单引号包起来。

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

Model Armor 响应净化

用 Google Cloud Model Armor 对响应做 prompt injection 扫描, 减少把恶意内容喂给 agent 的风险。

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

环境变量

• GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE
• GOOGLE_WORKSPACE_CLI_SANITIZE_MODE, warn 或 block

环境变量速查

• GOOGLE_WORKSPACE_CLI_TOKEN
• GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
• GOOGLE_WORKSPACE_CLI_CLIENT_ID
• GOOGLE_WORKSPACE_CLI_CLIENT_SECRET
• GOOGLE_WORKSPACE_CLI_CONFIG_DIR
• GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE
• GOOGLE_WORKSPACE_CLI_SANITIZE_MODE
• GOOGLE_WORKSPACE_PROJECT_ID

与 AI agent 结合

仓库自带大量 SKILL.md, 并提供 npx skills add 的安装方式, 方便把 Workspace 能力注入到 agent 系统中。

npx skills add https://github.com/googleworkspace/cli
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive

如果你用 OpenClaw, 也可以把 skills 目录直接链接进 ~/.openclaw/skills/ 来保持同步。

排障速记

Access blocked 或 403

常见原因, OAuth consent screen 处于 testing mode, 但没有把当前账号加到 Test users。把账号加进去后重试 gws auth login。

redirect_uri_mismatch

OAuth client 类型建错了, 必须是 Desktop app。

accessNotConfigured

对应 API 没启用, 需要在 GCP Console 里 Enable, 等十秒左右再重试。

我自己的用法建议

1. 一开始只开你需要的 scopes, 尤其是 testing mode, 省得 scope 太多直接登录失败。
2. 用 gws schema ... 当成 API 的实时文档, 比翻网页快。
3. 所有输出都 JSON, 你要养成 jq 管道习惯, 能把大量自动化直接串起来。
4. 在 agent 场景里, 强烈建议开 --sanitize 或全局模板, 这玩意实际能挡掉不少“把提示词塞进邮件正文”的阴招。