Google Workspace CLI

gws

面向 Google Workspace 全家桶的统一命令行工具，专为人类与 AI Agent 打造。
支持 Drive、Gmail、Calendar 以及所有 Workspace API。零样板代码，输出结构化 JSON，内置 40+ 个 Agent 技能。

说明

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

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

gws 不附带静态的命令列表。它会在运行时读取 Google 自身的 Discovery Service，并动态构建整个命令面。当 Google Workspace 新增 API 端点或方法时，gws 会自动识别。

重要

本项目仍在积极开发中，在迈向 v1.0 的过程中可能会出现破坏性变更。

目录

• 前置条件
• 安装
• 快速开始
• 为什么选择 gws？
• 认证
• AI Agent 技能
• 高级用法
• 环境变量
• 退出码
• 架构
• 故障排查
• 开发

前置条件

• Node.js 18+ — 用于 npm install（或从 GitHub Releases 下载预构建的二进制文件）
• 一个 Google Cloud 项目 — OAuth 凭据所需。你可以通过 Google Cloud Console、gcloud 命令行工具，或使用 gws auth setup 命令来创建。
• 一个可访问 Google Workspace 的 Google 账号

安装

推荐的安装方式是从 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 Agent — 每个响应都是结构化 JSON。配合内置的 Agent 技能使用，你的大模型无需自定义工具即可管理 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'

认证

该命令行工具支持多种认证流程，因此可在笔记本电脑、CI 和服务器上使用。

应该使用哪种设置？

交互式（本地桌面）

凭据以 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 命令行。如果你没有安装 gcloud，请改用下方的手动设置。

警告

测试模式下的范围限制： 如果你的 OAuth 应用未经验证（测试模式）， Google 会将授权范围限制在约 25 个。recommended 范围预设包含 85 个以上 范围，对于未经验证的应用将会失败（尤其是 @gmail.com 账户）。 请改为选择单独的服务来过滤范围选择器：

gws auth login -s drive,gmail,sheets

手动 OAuth 设置（Google Cloud 控制台）

当 gws auth setup 无法自动创建项目或客户端，或者你希望完全手动控制时，请使用此方法。

1. 在目标项目中打开 Google Cloud 控制台：
   • OAuth 同意屏幕：https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>
   • 凭据：https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>
2. 如有提示，配置 OAuth 品牌信息与受众：
   • 应用类型：外部（测试模式即可）
3. 在 测试用户 下添加你的账户
4. 创建 OAuth 客户端：
   • 类型：桌面应用
5. 下载客户端 JSON 文件，并保存到：
   • ~/.config/gws/client_secret.json

重要

你必须将自己添加为测试用户。 在 OAuth 同意屏幕中，点击 测试用户 → 添加用户，然后输入你的 Google 账户邮箱。否则登录时会出现通用的“访问被阻止”错误。

然后运行：

gws auth login

浏览器辅助授权（人工或 Agent）

你可以手动完成 OAuth 授权，也可以使用浏览器自动化完成。

• 人工流程：运行 gws auth login，打开输出的 URL，批准授权范围。
• Agent 辅助流程：Agent 打开 URL，选择账户，处理同意提示，并在本地回调成功后将控制权交还给你。

如果同意页面显示 “Google 尚未验证此应用”（测试模式），请点击 继续。 如果出现范围复选框，请在继续前勾选所需范围（或点击 全选）。

无头 / 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
   

服务账户（服务器到服务器）

指向你的密钥文件即可，无需登录。

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

预先获取的访问令牌

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

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

优先级

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

AI Agent 技能

该仓库提供 100 多个 Agent 技能（SKILL.md 文件），涵盖每个受支持的 API，外加用于常见工作流的更高层辅助工具，以及针对 Gmail、Drive、Docs、Calendar 和 Sheets 的 50 个精选示例。完整列表请参阅技能索引。

# 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

# 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/

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

   gws auth setup
   

2. 将扩展安装到 Gemini CLI 中：

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

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

高级用法

分段上传

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

分页

Google Sheets — Shell 转义

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]]}'

辅助命令

部分服务在自动生成的 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 …

完整辅助命令参考：

示例：

# Send an email
gws gmail +send --to [email protected] --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（响应净化）

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

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

环境变量

所有变量均为可选项。可参阅 .env.example 获取可直接复制的模板。

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

退出码

gws 使用结构化退出码，脚本无需解析错误输出即可根据故障类型进行分支处理。

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

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

架构

gws 采用两阶段解析策略：

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

所有输出（包括成功结果、错误信息和下载元数据）均为结构化 JSON。

故障排查

登录时出现 “Access blocked” 或 403

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

解决方法： 在你的 GCP 项目中打开 OAuth 同意屏幕 → Test users → Add users → 输入你的 Google 账号邮箱。然后重新运行 gws auth login。

出现 “Google hasn't verified this app”

应用处于测试模式时属于正常现象。点击 Advanced → Go to <app name> (unsafe) 继续。个人使用是安全的；只有需要向其他用户发布应用时才需要进行验证。

权限范围过多 / 同意屏幕错误

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

解决方法： 仅选择你需要的权限范围：

gws auth login --scopes drive,gmail,calendar

未找到 gcloud 命令行工具

gws auth setup 需要 gcloud 命令行工具来自动创建项目。你有以下三种选择：

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

redirect_uri_mismatch

OAuth 客户端的类型不是 桌面应用。请在 凭据 页面删除现有客户端，新建类型为 桌面应用 的客户端，然后下载新的 JSON 文件。

API 未启用 — accessNotConfigured

如果 GCP 项目未启用所需的 Google API，你会看到原因为 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 控制台中点击 启用。
3. 等待约 10 秒，然后重试你的 gws 命令。

提示

你也可以运行 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

免责声明

注意

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