gws

Google Workspace 的通用 CLI — 专为人类和 AI 智能体设计。 支持 Drive、Gmail、Calendar 以及所有 Workspace API。无需样板代码，提供结构化的 JSON 输出，并包含 40 多种 AI 智能体技能。

[!NOTE] 这不是 Google 官方支持的产品。

npm install -g @googleworkspace/cli

gws 不会附带静态的命令列表。它在运行时读取 Google 自身的 Discovery Service，并动态构建其整个命令体系。当 Google Workspace 添加 API 端点或方法时，gws 会自动将其纳入支持。

[!IMPORTANT] 该项目正处于活跃开发阶段。在迈向 v1.0 的过程中，可能会出现破坏性变更（Breaking changes）。

目录

• 前提条件
• 安装
• 快速入门
• 为什么选择 gws？
• 身份验证
• AI 智能体技能
• 高级用法
• 环境变量
• 退出代码
• 架构
• 故障排查
• 开发

前提条件

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

安装

npm install -g @googleworkspace/cli

npm 包中捆绑了适用于你操作系统和架构的预构建原生二进制文件。无需 Rust 工具链。

预构建的二进制文件也可以在 GitHub Releases 页面获取。

或者通过源码构建：

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

也可以使用 Nix flake：

nix run github:googleworkspace/cli

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

brew install googleworkspace-cli

快速入门

gws auth setup     # 指导你完成 Google Cloud 项目配置
gws auth login     # 后续 OAuth 登录
gws drive files list --params '{"pageSize": 5}'

为什么选择 gws？

面向人类 — 无需再对着 REST 文档编写 curl 请求。gws 为每个资源提供 --help 指令、用于预览请求的 --dry-run 模式以及自动分页功能。

面向 AI 智能体 — 每个响应都是结构化的 JSON。配合内置的智能体技能，你的 LLM（大语言模型）无需定制工具即可管理 Workspace。

# 列出最近的 10 个文件
gws drive files list --params '{"pageSize": 10}'

# 创建电子表格
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# 发送 Chat 消息
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# 检查任何方法的请求/响应结构（Schema）
gws schema drive.files.list

# 以 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       # 一次性操作：创建云项目、启用 API 并登录
gws auth login       # 后续的范围选择和登录

gws auth setup 需要 gcloud CLI。如果你没有 gcloud，请使用下方的 手动配置。

[!WARNING] 测试模式下的范围限制： 如果你的 OAuth 应用处于未验证状态（测试模式），Google 会将授权范围限制在约 25 个以内。recommended 预设包含 85 个以上的范围，对于未验证的应用（特别是 @gmail.com 账号）会导致失败。请选择个别服务来筛选范围选择器：

gws auth login -s drive,gmail,sheets

手动 OAuth 配置 (Google Cloud Console)

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

1. 打开...