google-workspace-cli

Google Workspace CLI

使用开源 gws CLI（github.com/googleworkspace/cli，Apache-2.0）进行 Google Workspace 管理的专业指导与自动化。该 CLI 通过 Google 的 Discovery Service 动态生成命令界面，因此覆盖所有受支持的 Workspace API，以及以 + 为前缀的辅助命令。本 Skill 额外提供本地 Python 工具（诊断、认证指南、配方目录、安全审计、输出分析器）。

在编写脚本前请先验证： gws 在运行时根据 Google 的 API 发现文档生成命令，且该 CLI 仍处于 v1.0 之前的版本。在将命令放入自动化脚本前，请务必使用 gws --help、gws <service> --help 或 gws schema <service>.<resource>.<method> 确认命令的确切界面。本 Skill 中标注 (verify) 的命令仅为 gws <service> <resource> <method> 模式的示例，必须对照您安装的版本进行核实。

---

快速开始

检查安装

# Verify gws is installed and authenticated
python3 scripts/gws_doctor.py

发送邮件

gws gmail +send --to "[email protected]" \
  --subject "Weekly Update" --body "Here's this week's summary..."

列出 Drive 文件

gws drive files list --params '{"pageSize": 20}' | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table

---

安装

npm（推荐；需要 Node.js 18+）

npm install -g @googleworkspace/cli
gws --version

Homebrew（macOS/Linux）

brew install googleworkspace-cli

Cargo（从源码构建）

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

预编译二进制文件

从 github.com/googleworkspace/cli/releases 下载适用于 macOS、Linux 或 Windows 的版本。Nix 用户可使用：nix run github:googleworkspace/cli。

验证安装

python3 scripts/gws_doctor.py
# Checks: PATH, version, auth status, service connectivity

---

认证

OAuth 设置（交互式）

# Step 1: Create Google Cloud project and OAuth credentials
python3 scripts/auth_setup_guide.py --guide oauth

# Step 2: Run interactive auth setup (uses gcloud if available)
gws auth setup

# Step 3: Log in, requesting only the scopes you need
gws auth login -s drive,gmail,sheets

无头模式 / CI

# Generate setup instructions
python3 scripts/auth_setup_guide.py --guide service-account

# Export credentials from an interactive machine, then point the CLI at them
gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

环境变量

# Generate .env template
python3 scripts/auth_setup_guide.py --generate-env

变量	用途
GOOGLE_WORKSPACE_CLI_CLIENT_ID	OAuth 客户端 ID
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET	OAuth 客户端密钥
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE	导出的凭据 JSON 文件路径
GOOGLE_WORKSPACE_CLI_TOKEN	预先获取的 OAuth 令牌
GOOGLE_WORKSPACE_CLI_CONFIG_DIR	覆盖默认配置位置
GOOGLE_WORKSPACE_CLI_LOG	启用调试日志

验证认证

python3 scripts/auth_setup_guide.py --validate --json
# Tests each service endpoint

---

工作流 1：Gmail 自动化

目标： 自动化邮件操作——发送、搜索、标签与过滤器管理。

发送、回复、转发（辅助命令）

# Send a new email
gws gmail +send --to "[email protected]" \
  --subject "Proposal" --body "Please find attached..."

# Reply to a message (auto-threading); check exact flags with: gws gmail +reply --help
gws gmail +reply ...

# Forward a message; check exact flags with: gws gmail +forward --help
gws gmail +forward ...

# Unread inbox summary
gws gmail +triage

搜索与查看（发现类命令）

发现类命令遵循 gws <service> <resource> <method> 格式，通过 --params（查询/路径参数）和 --json（请求体）以 JSON 形式传入请求参数。请先查看任意方法的确切 schema：

# What does messages.list accept? (verify)
gws schema gmail.users.messages.list

# Search emails (verify against the schema above)
gws gmail users messages list --params '{"userId": "me", "q": "from:[email protected] after:2025/01/01"}' \
  | python3 scripts/output_analyzer.py --count

# List labels (verify)
gws gmail users labels list --params '{"userId": "me"}'

批量操作

先使用 --dry-run，并使用 --page-all 进行分页（每页输出一行 JSON）：

# Preview, then archive read emails older than 30 days (verify method schema first)
gws gmail users messages list --params '{"userId": "me", "q": "is:read older_than:30d"}' --page-all \
  | python3 scripts/output_analyzer.py --select "id" --format json
# Then feed ids to gmail users messages modify (see: gws schema gmail.users.messages.modify)

---

工作流 2：Drive 与 Sheets

目标： 管理文件、创建电子表格、配置共享并导出数据。

文件操作

# List files
gws drive files list --params '{"pageSize": 50}' \
  | python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table

# Upload a file (helper)
gws drive +upload ./report.pdf --name "Q1 Report"

# Create a Google Sheet
gws sheets spreadsheets create --json '{"properties": {"title": "Budget 2026"}}'

# Download/export — inspect the method first (verify)
gws schema drive.files.export

共享（请先验证 schema）

# Inspect the permissions API surface
gws schema drive.permissions.create

# Share with user (verify against schema)
gws drive permissions create --params '{"fileId": "<FILE_ID>"}' \
  --json '{"type": "user", "role": "writer", "emailAddress": "[email protected]"}'

# List who has access (verify)
gws drive permissions list --params '{"fileId": "<FILE_ID>"}'

Sheets 数据

# Read values (helper); check exact flags with: gws sheets +read --help
gws sheets +read ...

# Append a row (helper); check exact flags with: gws sheets +append --help
gws sheets +append ...

# Or use discovery methods (verify):
gws schema sheets.spreadsheets.values.update
gws sheets spreadsheets values get --params '{"spreadsheetId": "<SHEET_ID>", "range": "Sheet1!A1:D10"}'

---

工作流 3：日历与会议

目标： 安排日程、查找可用时间并生成站会报告。

日程管理

# Create an event (helper); check exact flags with: gws calendar +insert --help
gws calendar +insert ...

# Upcoming events (helper, timezone-aware)
gws calendar +agenda

# Or via discovery (verify):
gws schema calendar.events.insert
gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}'

查找可用时间

# Free/busy via the Calendar API (verify schema first)
gws schema calendar.freebusy.query
gws calendar freebusy query --json '{"timeMin": "...", "timeMax": "...", "items": [{"id": "[email protected]"}]}'

站会报告（工作流辅助命令）

# Today's meetings + tasks
gws workflow +standup-report \
  | python3 scripts/output_analyzer.py --format table

# Next meeting prep; check exact flags with: gws workflow +meeting-prep --help
gws workflow +meeting-prep

---

工作流 4：安全审计

目标： 审计 Google Workspace 安全配置，并生成修复命令。

运行完整审计

# Full audit across all services
python3 scripts/workspace_audit.py --json

# Audit specific services
python3 scripts/workspace_audit.py --services gmail,drive,calendar

# Demo mode (no gws required)
python3 scripts/workspace_audit.py --demo

审计检查项

领域	检查项	风险
Drive	已启用外部共享	数据外泄
Gmail	自动转发规则	数据外泄
Gmail	DMARC/SPF/DKIM 记录	邮件欺骗
Calendar	默认共享可见性	信息泄露
OAuth	第三方应用授权	未经授权的访问
Admin	超级管理员数量	权限提升
Admin	两步验证强制执行	账户接管

审查与修复

# Review findings
python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py \
  --filter "status=FAIL" --select "area,check,remediation"

# Execute remediation (example: check current Drive settings first; verify)
gws drive about get --params '{"fields": "*"}'
# Follow remediation commands from audit output (verify each against gws --help)

---

Python 工具

脚本	用途	用法
gws_doctor.py	运行前诊断	python3 scripts/gws_doctor.py [--json] [--services gmail,drive]
auth_setup_guide.py	引导式认证设置	python3 scripts/auth_setup_guide.py --guide oauth
gws_recipe_runner.py	配方目录与运行器	python3 scripts/gws_recipe_runner.py --list [--persona pm]
workspace_audit.py	安全与配置审计	python3 scripts/workspace_audit.py [--json] [--demo]
output_analyzer.py	JSON/NDJSON 分析	gws ... --json | python3 scripts/output_analyzer.py --count

所有脚本均仅使用标准库，支持 --json 输出，并内置带有示例数据的演示模式。

---

最佳实践

安全

1. 使用最小权限范围的 OAuth，只申请每个工作流所需的权限
2. 将令牌存储在系统密钥环中，切勿保存在明文文件里
3. 每 90 天轮换一次服务账号密钥
4. 每季度审计一次第三方 OAuth 应用的授权
5. 在执行大批量破坏性操作前，先使用 --dry-run

自动化

1. 所有 gws 输出都是结构化 JSON，可通过管道交给 output_analyzer.py 进行筛选和聚合
2. 多步骤操作请使用 gws workflow +* 辅助命令，而不是串联原始命令
3. 将本地配方目录（gws_recipe_runner.py）用作命令模板，然后用 gws --help 逐一核对
4. --page-all 会为每一页输出一行 JSON（NDJSON），便于流式处理大型结果集
5. 在执行任何请求前，使用 --dry-run 预览该请求

性能

1. 通过 --params 中 API 的 fields 参数只请求需要的字段（可减小数据负载）
2. 浏览数据时，使用 --params 中的 pageSize 限制结果数量
3. 仅在需要完整数据集时使用 --page-all；可通过 --page-limit / --page-delay 进行调整
4. 优先使用 + 辅助命令（单次优化调用），而不是手动串联 API 调用
5. 将常用数据（例如标签 ID、文件夹 ID）缓存到变量中

---

限制

约束	影响
OAuth 令牌 1 小时后过期	长时间运行的脚本需要重新认证
API 速率限制（按用户、按服务）	批量操作可能触发 429 错误
各服务所需权限范围不同	认证时必须申请正确的权限范围
CLI 处于 v1.0 之前的状态	版本之间可能出现破坏性变更
需要 Google Cloud 项目	免费，但需要在 Cloud Console 中完成设置
Admin API 需要管理员权限	部分审计检查需要 Workspace 管理员角色

各服务所需权限范围

# List scopes for specific services
python3 scripts/auth_setup_guide.py --scopes gmail,drive,calendar,sheets

服务	关键权限范围
Gmail	gmail.modify、gmail.send、gmail.labels
Drive	drive.file、drive.metadata.readonly
Sheets	spreadsheets
Calendar	calendar、calendar.events
Admin	admin.directory.user.readonly、admin.directory.group
Tasks	tasks