googleworkspace/cli · 上手攻略

仓库：googleworkspace/cli
链接：https://github.com/googleworkspace/cli
分类：Google Workspace · CLI 工具 · AI Agent
作者：Tom
更新：2026-08-06

这是什么

Google Workspace CLI（gws）是 Google 官方开源的命令行工具，通过 Google Discovery Service 动态构建命令体系，一套 CLI 覆盖 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 等全部 Google Workspace API。

核心设计哲学：运行时动态生成命令——不维护静态命令列表，而是直接读取 Google 官方 Discovery 文档。无论 Google 新增什么 API 或方法，gws 下次运行即自动获得，无需版本更新。

同时附赠 100+ Agent Skills（SKILL.md），让 AI Agent 原生操作 Google Workspace。

解决什么问题

Google Workspace API 能力强大，但直接调 REST 接口门槛高： - 需要查文档理解 OAuth 流程 - 写 curl 命令复杂，参数容易配错 - 没有统一 CLI，不同服务要用不同工具

gws 把 Google Workspace API 变成普通命令行工具，同时输出结构化 JSON，专门适配 AI Agent 场景。

快速安装

下载预编译二进制（推荐，无依赖）

# 从 GitHub Releases 下载对应平台二进制
# https://github.com/googleworkspace/cli/releases

# macOS (Apple Silicon)
curl -fsSL https://github.com/googleworkspace/cli/releases/latest/download/gws-macos-arm \
  -o /usr/local/bin/gws && chmod +x /usr/local/bin/gws

# macOS (Intel)
curl -fsSL https://github.com/googleworkspace/cli/releases/latest/download/gws-macos-intel \
  -o /usr/local/bin/gws && chmod +x /usr/local/bin/gws

# Linux
curl -fsSL https://github.com/googleworkspace/cli/releases/latest/download/gws-linux-amd \
  -o /usr/local/bin/gws && chmod +x /usr/local/bin/gws

npm 全局安装

npm install -g @googleworkspace/cli

Homebrew（macOS/Linux）

brew install googleworkspace-cli

Nix（一行安装）

nix run github:googleworkspace/cli

源码构建（需 Rust）

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

⚠️ 项目仍处活跃开发中，v1.0 前可能有 Breaking Changes。生产使用建议锁定版本。

认证配置

最简路径：`gws auth setup`（需 gcloud CLI）

# 只需运行一次，自动化完成：
# 1. 创建 GCP 项目
# 2. 启用所需 API
# 3. 配置 OAuth Consent
# 4. 引导登录
gws auth setup

# 后续登录（已有项目配置）
gws auth login

手动 OAuth（无 gcloud）

在 Google Cloud Console 创建 OAuth Client（类型：Desktop app）
下载 JSON 保存到 ~/.config/gws/client_secret.json
运行 gws auth login

⚠️ 测试模式 OAuth Scope 限制：未验证的 OAuth App 受 Google 限制最多 25 个 Scope。若安装报错，登录时缩小范围：gws auth login -s drive,gmail,sheets

服务账号（服务器/无头环境）

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

复用现有 Token

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
gws drive files list

核心用法

快速上手

# 认证后立刻开始
gws auth login
gws drive files list --params '{"pageSize": 5}'

Drive

# 列出文件（NDJSON 流式，支持自动分页）
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

# 上传文件
gws drive files create --json '{"name": "report.pdf", "mimeType": "application/pdf"}' --content ./report.pdf

Gmail

# 列出邮件（取最新 5 封）
gws gmail messages list --params '{"maxResults": 5}'

# 发送邮件
gws gmail messages create \
  --json '{"to": [{"email": "recipient@example.com"}], "subject": "Hello"}' \
  --json-body '{"body": {"text": "Content here"}}'

Calendar

# 列出近期待办事件
gws calendar events list --params '{"calendarId": "primary", "timeMax": "2026-08-13T00:00:00Z"}'

Sheets

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

# 读取数据
gws sheets spreadsheets values get --params '{"spreadsheetId": "YOUR_ID", "range": "Sheet1!A1:E5"}'

Chat

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

探索 API Schema

# 任意方法查看请求/响应结构
gws schema drive.files.list

AI Agent Skills（100+ SKILL.md）

项目自带 100 多个 Agent Skill，覆盖每个 Workspace API，并附 50+ Gmail/Drive/Docs/Calendar/Sheets 配方：

# 安装所有 Skills（Claude Code / Codex 等通用）
npx skills add googleworkspace/cli

# 或查看 Skills 索引
# https://github.com/googleworkspace/cli/blob/main/docs/skills.md

AI Agent 安装 Skill 后，可直接用自然语言操作 Google Workspace："帮我把昨天收到的邮件归档到 Drive 文件夹"——Agent 调用对应 gws 命令执行。

典型适用场景

个人效率自动化：CLI 查邮件、发日程、写表格，不用开浏览器
AI Agent 工作流：Agent Skill 让大模型操作 Workspace——读邮件→生成摘要→写 Sheets 报告
CI/CD 集成：GitHub Actions 中用 gws 做自动日报、定时数据同步、监控告警
服务器端操作：服务账号认证后，无头环境操作 Workspace（备份、迁移）
快速原型：用 --dry-run 预览 API 调用，对接 Google API 前先在 CLI 验证参数

坑与注意

坑点	说明
v1.0 前 Breaking Changes	项目仍活跃开发，生产锁定版本号
OAuth App 未验证的 Scope 限制	`gws auth setup` 触发的 App 含 85+ Scope，未验证账号超 25 Scope 上限会报错；改用 `gws auth login -s drive,gmail` 缩小范围
测试用户必须手动添加	手动创建 OAuth Client 后，需在 consent screen 添加 Test Users，否则登录报 "Access blocked"
凭证文件路径需正确	Linux/macOS：`~/.config/gws/client_secret.json`；Windows：参考文档
凭证加密依赖 OS Keyring	Linux 可能需要 `libsecret`（Debian: `apt install libsecret-1-dev`），否则 fallback 到明文文件
`--dry-run` 行为因端点而异	部分写操作在 dry-run 模式下会真正创建草稿，慎用
Node.js 18+ 才能用 npm 安装	二进制安装不需 Node.js

与同类对比

工具	覆盖服务	动态命令	Agent Skill	说明
gws	Drive/Gmail/Calendar/Sheets/Docs/Chat/Admin	✅	✅ 100+	Google 官方维护，动态跟上 API 更新
gcloud CLI	全 GCP（含 Workspace）	部分	❌	GCP 通用，Workspace 功能分散
gam（Google Apps Manager）	Workspace 主服务	❌ 静态	❌	老牌开源，成熟但无 Agent 设计
`curl` + OAuth	任一 Google API	❌	❌	门槛最高，参数易错

结论：gws 是目前最适合 AI Agent 场景的 Google Workspace CLI——动态命令意味着 Google 出新 API 你立刻能用，100+ Skill 让 Agent 原生理解所有 Workspace 操作。

一句话推荐结论

管理 Google Workspace？无论是你自己还是 AI Agent，gws 是目前最顺滑的入口——一套 CLI + 动态命令 + 100 个 Agent Skill，别再手写 curl 了。

最小可跑命令

# 1. 安装（任选其一）
npm install -g @googleworkspace/cli   # Node.js 环境
# 或下载二进制：https://github.com/googleworkspace/cli/releases

# 2. 认证
gws auth setup    # 有 gcloud 时自动完成
# 或手动配置 client_secret.json 后：
gws auth login

# 3. 验证
gws drive files list --params '{"pageSize": 3}'

硬件/版本备注：Node.js 18+（npm 安装）；二进制版无语言依赖；macOS/Linux/Windows 均支持；gws auth setup 需 gcloud CLI 已登录；GCP 项目需启用对应 API（setup 命令会自动处理）。

原始链接：https://github.com/googleworkspace/cli | Skills 索引 | CI 流程 | npm: @googleworkspace/cli | Google 官方（非正式支持产品），无特定 commit SHA 引用。