@googleworkspace/cli

什么是 googleworkspace-cli？

googleworkspace/cli（发布为 @googleworkspace/cli）是 Google Workspace 的命令行工具。它让您使用单一 CLI 操作多个 Workspace API——如 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 等。

命令界面在运行时动态构建，基于 Google 的 Discovery Service，而不是提供固定的命令列表。该项目还被描述为包含“AI agent skills”，CLI 强调结构化 JSON 输出以支持自动化。

主要特性

• 单一 CLI 操作多个 Workspace 服务：提供统一接口与 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 等 Workspace API 交互。
• 基于 Discovery Service 的动态命令生成：命令和方法在运行时通过读取 Google 的 Discovery Service 构建，因此无需静态命令列表即可获取新端点/方法。
• 结构化 JSON 输出：专为自动化和 AI 代理设计；响应以结构化 JSON 返回。
• API 方法的 Schema introspection：使用 gws schema <...> 检查方法的请求/响应 schema。
• 请求模拟和分页助手：使用 --dry-run 预览请求，--page-all 流式传输分页结果（可选输出至 jq 等工具）。
• 多种认证流程：支持适用于本地、CI 和服务器的设置/登录流程，包括与 gcloud 的集成（若可用）。
• 内置代理技能：仓库文档指出包含“40+ agent skills”。

如何使用 googleworkspace-cli

1. 安装 CLI：
   • 通过 npm：npm install -g @googleworkspace/cli
   • 或从 GitHub Releases 使用预构建二进制文件
   • 或从源码构建：cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux 还支持 Homebrew；提供 Nix flake。)
2. 认证（一次性项目设置，然后登录）：
   • gws auth setup（需安装并认证 gcloud）
   • gws auth login（后续 OAuth 登录）
   • 对于手动令牌或控制台流程，文档列出了环境变量和手动 OAuth 设置路径。
3. 针对资源运行命令。文档中的示例工作流包括：
   • 列出文件：gws drive files list --params '{"pageSize": 5}'
   • 创建电子表格：gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • 发送 Chat 消息：gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • 检查 schema：gws schema drive.files.list

使用场景

• 使用分页和 JSON 自动化 Drive 工作流：从 Drive 列表端点流式传输大型结果集，并使用下游工具处理（例如结合 --page-all 输出与 jq）。
• 无需编写原始 REST 调用即可发送 Gmail/Chat/Calendar 请求：使用 CLI 的资源导向命令创建或更新对象，依赖生成的界面。
• 执行前验证请求结构：使用 --dry-run 预览 CLI 将发送的内容，有助于为 Sheets、Chat 等资源生成负载。
• 围绕 Workspace API 构建 AI 代理工具：利用结构化 JSON 响应和内置代理技能，让 LLM 驱动的代理以更少自定义代码决定调用哪些 Workspace 操作。
• 从 CLI 发现如何调用 API 方法：当您知道方法存在但不确定确切请求形状时，使用 gws schema <method> 检查请求/响应 schema。

常见问题

• googleworkspace-cli 是 Google 官方产品吗？ 不是。仓库注明：“This is not an officially supported Google product。”

• 它有固定的命令列表吗？ 没有。文档指出不提供静态命令列表；它在运行时读取 Google 的 Discovery Service 并动态构建命令界面。

• 安装和运行需要什么？ npm 安装流程需 Node.js 18+。认证需要 Google Cloud 项目 用于 OAuth 凭据，以及具有 Workspace 访问权限的 Google 帐户。

• 应该使用哪种认证设置？ 文档描述了多种路径：

  • 使用已安装并认证的 gcloud 进行 gcloud 辅助设置（gws auth setup）
  • 自动化不可用时通过 Google Cloud Console 手动 OAuth 设置
  • 通过环境变量的令牌/手动凭据（按文档）

• 开发/测试期间有范围相关的限制吗？ 是的。文档警告，如果 OAuth 应用未验证（测试模式），Google 会将同意限制在约 25 个范围，且推荐的范围预设（85+ 范围）对未验证应用会失败——尤其是 @gmail.com 帐户。

替代方案

• 直接使用 curl 或 HTTP 客户端调用 REST API：可直接调用 Workspace 端点，但需自行处理请求格式、分页和认证细节。
• 特定 Workspace 服务的官方 SDK（例如，特定语言的 Google APIs 库）：为特定服务提供类型化客户端方法，但通常每个 API 需要独立的代码路径，而非单一动态生成的 CLI 接口。
• 其他 Google APIs CLI 工具：其他 CLI 可能专注于特定服务或使用静态命令集；视工具而定，可能无法提供此处所述的动态 Discovery Service 驱动命令生成或结构化 JSON + 模式自省工作流。