gws-cli

gws-cli

当任务应通过 Google Workspace CLI 执行，而不是手写 HTTP 请求或临时编写 API 封装时，使用此技能。

何时使用此技能

• 用户要求与 Google Drive、Gmail、Sheets、Docs、Slides、Calendar、Chat、Tasks、People、Meet 或 Workspace Admin API 交互。
• 用户需要结构化的 JSON 输出，以便 Agent 轻松检查。
• 用户需要在构建请求前检查 Google API 架构。
• 用户需要可在本地、CI 或无头环境中运行的可重复 CLI 工作流。

必需的操作流程

1. 确认已安装 gws，且可通过 PATH 访问。
2. 进行 API 调用前检查身份验证状态。
3. 在组合标志前，使用 gws schema 或 gws <service> --help 检查目标方法。
4. 优先执行只读命令。
5. 对于写入、更新或删除操作，执行前先向用户确认意图。
6. 如果命令支持本地验证且操作有风险，优先使用 --dry-run。

快速入门

# Install the CLI
npm install -g @googleworkspace/cli

# Check the binary and auth status
bash scripts/check-prereqs.sh

# Inspect command space
gws drive --help
gws schema drive.files.list

# Run a read-only command
gws drive files list --params '{"pageSize": 10}' --format json

身份验证工作流

选择满足任务需求的最简身份验证流程。

本地交互式

gws auth setup
gws auth login

服务账号

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
gws auth status

CI 或无头流程

• 优先使用导出的凭据或基于服务账号的执行方式。
• 绝不要向用户回显密钥。
• 如果缺少凭据，请停止并询问合适的身份验证设置，不要自行猜测。

更多详情请参阅 references/REFERENCE.md。

命令发现工作流

执行前务必先检查。

# Browse resources and helper commands for a service
gws sheets --help

# Inspect a specific method schema
gws schema sheets.spreadsheets.values.get

使用架构输出确定：

• 必需的 --params 值
• 是否需要通过 --json 提供请求正文
• 是否适用分页或文件上传标志
• API 预期的字段名称和类型

命令模式

只读列表或获取

gws drive files list --params '{"pageSize": 10}' --format json
gws gmail users messages get --params '{"userId": "me", "id": "MESSAGE_ID"}' --format json

经明确确认后创建或更新

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}' --format json
gws docs documents batchUpdate --params '{"documentId": "DOC_ID"}' --json '{"requests": [...]}' --format json

基于架构构建请求

gws schema calendar.events.insert
gws calendar events insert --params '{"calendarId": "primary"}' --json '{"summary": "Standup", "start": {"dateTime": "2026-03-07T09:00:00Z"}, "end": {"dateTime": "2026-03-07T09:15:00Z"}}'

分页

gws drive files list --params '{"pageSize": 100}' --page-all

文件上传或下载

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' --output ./download.bin

安全规则

• 将 create、insert、update、patch、delete 以及会更改状态的辅助命令视为写入操作。
• 执行写入操作前，确认目标资源、身份和范围。
• 绝不要打印令牌、OAuth 客户端密钥或服务账号 JSON 内容。
• 除非用户明确需要面向人的表格，否则优先使用 --format json。
• 有意使用 --page-all，因为它会将输出格式改为 NDJSON。
• 如果上游 API 或 CLI 帮助信息含糊不清，请重新检查架构，不要猜测标志名称。

可用的支持文件

• references/REFERENCE.md：安装、身份验证和常见命令模板
• scripts/check-prereqs.sh：本地环境检查

故障排除

• 如果缺少 gws，请从 npm 或 GitHub 版本发布页安装，确认其位于 PATH 中，然后重新运行 bash scripts/check-prereqs.sh。
• 如果 gws auth status 显示没有凭据，请运行 gws auth setup 和 gws auth login，或在服务账号流程中导出 GOOGLE_APPLICATION_CREDENTIALS。
• 如果 gws auth login 因 OAuth 客户端限制而失败，请在适当情况下优先使用上游手动 OAuth 流程或服务账号。
• 如果请求返回 403 Forbidden 或权限不足，请在重试前确认当前身份、API 是否已启用、作用域以及资源共享设置。
• 如果方法未知，请先使用 gws <service> --help 确认服务别名，不要假定 REST 方法名称可以直接映射。
• 如果请求未通过架构验证，请重新运行 gws schema <service.resource.method>，并逐一核对命令中每个必需字段的名称。
• 如果 --page-all 意外改变了输出格式，请注意分页输出会变成 NDJSON，应逐行解析。