cli

图1：gws 项目 Logo

你每天在 Gmail 里手动翻邮件、Drive 里找文件、日历里核对会议——这些重复操作，正是一个 Google 工程师在 2025 年试图解决的问题。他的想法很简单：能不能用一条命令，直接操控所有 Google Workspace 数据？

这就是 Google Workspace CLI（gws） 的诞生背景。一个用 Rust 编写的命令行工具，如今在 GitHub 上已收获超过 26,500 颗星，成为 Google Workspace 生态中 star 最高的开源 CLI 项目。不同于传统的 Google API 封装库，它的核心创新在于：根本不需要提前写好命令列表。

动态发现：永不落伍的 API 适配

图2：GitHub 仓库预览

Google 拥有上百个 API——Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin……传统 CLI 工具的做法是：维护一个命令列表，每次 Google 新增接口，就更新代码。维护成本极高，且永远落后于 Google 的更新节奏。

gws 的解决思路堪称巧妙：它直接调用 Google 官方的 Discovery Service，这是 Google 用来描述自身所有 API 接口的元数据服务。gws 在运行时动态读取这些元数据，自动构建完整的命令树。当 Google 明天上线一个新的 API 或方法时，gws 用户在同一天就能使用，无需任何代码更新。

这相当于给你的 AI 代理装上了一双"实时读取 Google 文档"的眼睛。无论是发送 Chat 消息、创建日历事件，还是批量导出 Drive 文件，AI 都能通过 gws 完成，无需为每个操作手写 API 调用代码。

面向人类，也面向 AI

gws 的设计哲学明确区分了两类用户：

对于普通开发者，gws 提供了干净的命令行界面。每个操作都支持 --help 查看详细文档、--dry-run 预览即将发送的请求、自动分页等实用功能。用 gws drive files list --page-all 就能一次性导出所有文件，--sanitize 标志还能对 AI 模型输出进行安全过滤（Model Armor）。

对于 AI 代理，gws 提供了 100+ Agent Skills。这些 SKILL.md 文件描述了每个 API 的用途、参数和使用场景，AI 模型可以直接理解"如何用 gws 发送 Gmail"或"如何用 gws 创建 Sheet 报表"，无需人类预先编写复杂的 prompt 注入代码。更贴心的是，项目还提供了 50+ 精选配方（recipes），覆盖 Gmail、Drive、Docs、Calendar、Sheets 等高频场景。gws 还支持 Gemini CLI 扩展，可以直接 gemini extensions install 集成。

技术架构：Rust + npm 的双轨发行

图3：Google Workspace 开源组织头像

项目主体采用 Rust 编写，代码库分为两个核心 crate：

• crates/google-workspace：对 Google Discovery API 的封装，处理认证、请求构建和响应解析
• crates/google-workspace-cli：命令行界面实现，解析参数、渲染输出、管理子命令

有意思的是，虽然核心是 Rust 项目，但 npm 包 @googleworkspace/cli 的安装量也相当可观。npm 包底层通过 install.js 脚本自动从 GitHub Releases 下载对应平台的预编译二进制，兼顾了 Rust 的性能优势和 npm 生态的便利性。

认证机制是 gws 的另一个亮点。它支持四种认证方式，按优先级依次为：直接传入 Access Token → 提供 Credentials 文件路径 → 加密存储的凭证（gws auth login） → 明文 JSON 凭证文件。其中加密凭证使用 AES-256-GCM 加密，密钥存入系统 Keyring，兼顾了安全性和易用性。

安装与上手

gws 的安装极度简单，不依赖任何容器或复杂环境：

# 方式1: 直接下载预编译二进制（推荐）
# 访问 https://github.com/googleworkspace/cli/releases

# 方式2: npm 一键安装
npm install -g @googleworkspace/cli

# 方式3: 从源码构建（需要 Rust）
cargo install --git https://github.com/googleworkspace/cli --locked

# 方式4: Nix 一键运行
nix run github:googleworkspace/cli

# 方式5: Homebrew
brew install googleworkspace-cli

安装完成后，首次运行需要完成 Google Cloud 授权：

gws auth setup  # 交互式引导，自动创建 GCP 项目并启用 API

如果是在无头环境（服务器/CI），可以通过导出凭证的方式迁移认证状态。

局限与风险

需要客观指出几个现实问题：

1. 项目处于活跃开发中，距 v1.0 还有距离，中途可能有 Breaking Changes，生产环境使用需要锁定版本
2. OAuth 认证需要手动操作，虽然有 gws auth setup，但仍依赖 Google Cloud Console 的图形界面，不是完全无头友好
3. 没有 Web UI，纯命令行输出，JSON 结构化，适合集成但不适合可视化操作
4. 非 Google 官方产品，项目明确注明"not an officially supported Google product"，企业采购时需注意合规风险

行业意义

gws 的出现，代表了 AI 时代工具开发的一个新范式：不是给人写工具，而是给 AI 写工具。100+ Agent Skills 的设计不是附庸风雅，而是项目核心价值的一部分。当 AI 模型能够直接"读懂"一个工具的所有能力边界，自动化工作流的构建门槛将大幅降低。

从数据看，这个方向确实得到了社区的认可：26,500 颗星、1,400+ Fork、Google 内部员工参与维护，足以说明它在 Google Workspace 自动化领域的标杆地位。对于需要频繁与 Google Workspace 数据打交道的开发者或 AI 代理开发者，gws 值得优先评估。