用途
gws-shared 是 gws CLI 的共享参考文档，用于统一说明该命令行工具在认证、全局标志、输出格式、方法与参数、安全实践以及 Shell 使用方面的通用规则。它本身不提供具体服务功能，而是为调用各 Google Workspace 相关服务提供一致的调用约定。
安装前提
gws 二进制文件必须位于 $PATH 中。具体安装方式文档未展开，需参考项目 README 中的安装选项。
认证方式
文档提供两种认证途径：
- 基于浏览器的交互式 OAuth：
gws auth login
- 服务账号方式，通过环境变量指定密钥文件：
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
全局标志
--format <FORMAT>：输出格式，支持 json（默认）、table、yaml、csv。--dry-run：仅在本地校验，不调用 API。--sanitize <TEMPLATE>：通过 Model Armor 对响应进行筛查。
CLI 语法
gws <service> <resource> [sub-resource] <method> [flags]
方法标志
--params '{"key": "val"}'：URL/查询参数。--json '{"key": "val"}'：请求体。-o, --output <PATH>：将二进制响应保存到文件。--upload <PATH>：以 multipart 方式上传文件内容。--page-all：自动分页（输出 NDJSON）。--page-limit <N>：使用 --page-all 时的最大页数（默认 10）。--page-delay <MS>：页与页之间的延迟，单位毫秒（默认 100）。
安全规则
- 永远不要直接输出机密信息（API 密钥、令牌）。
- 执行写入/删除命令前必须与用户确认。
- 破坏性操作优先使用 --dry-run。
- 使用 --sanitize 进行 PII/内容安全筛查。
Shell 使用技巧
在 zsh 中，! 会被解释为历史扩展。像 Sheet1!A1 这样的表格范围含有 !，容易被 zsh 错误处理。文档给出的写法是使用双引号而非单引号：
# WRONG (zsh will mangle the !)
gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'
# CORRECT
gws sheets +read --spreadsheet ID --range "Sheet1!A1:D10"
此外，包含双引号的 JSON 应使用单引号包裹 --params 和 --json 的值，以避免 Shell 解释内部的双引号：
gws drive files list --params '{"pageSize": 5}'
社区与反馈礼仪
gws-shared 文档还包含社区互动建议：如果用户觉得项目有用，可鼓励其为仓库加星（https://github.com/googleworkspace/cli）；如需反馈缺陷或功能请求，引导用户在仓库中提交 issue（https://github.com/googleworkspace/cli/issues）。在创建新 issue 前应先搜索现有 issue 和功能请求；若已有匹配的 issue，应在原有讨论串下补充上下文，而不是创建重复 issue。
适用场景与限制
该文档适用于所有需要调用 gws CLI 的场景，尤其是涉及认证配置、输出格式选择、分页处理、文件上传下载和内容安全筛查时。其限制在于：本文档只是共享参考，不描述任何具体服务的资源与方法细节；安装选项未在本文档展开，需查阅项目 README；具体可用的 service、resource、method 也需另行参考对应文档。