gws CLI 的 Google Drive 实战指南动态命令、资源方法与文件上传全解析【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cligwsGoogle Workspace CLI是一个从 Google Discovery Service 动态构建命令面的单文件命令行工具覆盖 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 等全部 Workspace API。本文聚焦其中的gws drive命令族你将掌握 Drive v3 全部 12 个 API 资源about、files、drives、permissions、changes、comments、revisions 等的调用语法学会用--help与gws schema自查任意方法签名并通过upload辅助命令完成带自动元数据的文件上传。文章所有命令与参数均可在本仓库对应源码与技能文档中逐一验证。一、前提先掌握 gws 的认证、全局标志与安全规则gws drive依赖 skills/gws-shared/SKILL.md 中定义的公共约定。在使用任何 Drive 命令前请先完成认证与技能安装若本机缺少gws-shared技能可运行gws generate-skills生成。1.1 安装与认证gws二进制需位于$PATH。安装方式详见 README.md包括下载预编译二进制、npm install -g googleworkspace/cli、cargo install --git ... --locked或 Nix flake。认证支持两种主流方式# 浏览器 OAuth交互式推荐本地桌面 gws auth login # 服务账号服务器到服务器无需登录 export GOOGLE_APPLICATION_CREDENTIALS/path/to/key.json认证优先级从高到低为GOOGLE_WORKSPACE_CLI_TOKEN预取访问令牌→GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE凭证文件→gws auth login加密存储的凭证 →~/.config/gws/credentials.json明文凭证。1.2 全局标志Flag说明--format FORMAT输出格式json默认、table、yaml、csv--dry-run仅在本地校验不真正调用 API--sanitize TEMPLATE通过 Model Armor 筛查响应内容1.3 CLI 通用语法与方法级标志gws service resource [sub-resource] method [flags]Flag说明--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 Key/Token 等机密执行写/删命令前必须与用户确认破坏性操作优先使用--dry-run涉及 PII 或内容安全时使用--sanitize。二、命令面从何而来Discovery 动态构建机制gws drive的每一个资源与方法并非硬编码在二进制中。其架构采用两阶段解析见 README.md 的 Architecture 一节读取argv[1]识别服务名如drive拉取该服务的 Discovery Document缓存 24 小时缓存目录为~/.config/gws/cache/见 discovery.rs依据文档中的resources与methods构建clap::Command树重新解析剩余参数认证、构造 HTTP 请求并执行。因此当 Google 新增 Drive API 端点时gws drive会自动获得新命令无需升级 CLI。与此同时drive服务还注册了一个手写的辅助命令upload——辅助命令统一以前缀命名与 Discovery 自动生成的普通方法名永不冲突Helpertrait 定义见 helpers/mod.rsget_helper将drive映射到DriveHelper见 helpers/mod.rs。三、命令自检--help与gws schema调用任何 API 方法之前先用两个命令完成“查”的工作见 skills/gws-drive/SKILL.md 的 Discovering Commands 一节# 浏览资源与方法含 upload 辅助命令 gws drive --help # 查看某个方法的必填参数、类型与默认值 gws schema drive.resource.methodgws schema的输出用于构建你的--params与--json标志。其底层实现位于 schema.rs点分路径service.resource[.subresource].method会被解析find_method沿资源树逐层下钻定位方法schema.rs随后输出httpMethod、path、parameters含type、required、location、format、default、enum、repeated、deprecated等字段、scopes、requestBody与response的内联 schema--resolve-refs会递归展开$refschema.rs。典型用法# 查看 drive.files.list 的参数与响应结构 gws schema drive.files.list # 查看 File 类型定义 gws schema drive.File四、Drive v3 资源与方法全景gws drive resource method的完整命令面覆盖以下 12 个资源。下表为所有可用方法内容继承自 skills/gws-drive/SKILL.md 的 API Resources 一节并按官方语义补充说明资源方法说明aboutget获取用户、用户 Drive 及系统能力信息。必填必须设置fields参数以精确返回所需字段accessproposalsget/list/resolve按 ID 获取、列出文件上的访问提案、批准或拒绝访问提案。注意仅审批人可list非审批人返回 403approvalsget/list获取/列出文件上的 Approvalappsget/list获取指定应用/列出用户已安装应用changesgetStartPageToken/list/watch获取起始 pageToken、列出用户或共享盘的变更、订阅用户变更通知channelsstop停止通过该 channel 监听资源变更commentscreate/delete/get/list/update文件的评论管理。除delete外create/get/list/update均必填fields参数drivescreate/get/hide/list/unhide/update共享盘管理。list接受q搜索参数filescopy/create/download/export/generateIds/get/list/listLabels/modifyLabels/update/watch文件全生命周期操作详见下文专节operationsget获取长时间运行操作的最新状态可按 API 建议的间隔轮询permissionscreate/delete/get/list/update文件或共享盘的权限管理。警告同一文件上的并发权限操作不被支持只应用最后一次更新repliescreate/delete/get/list/update评论回复管理revisionsdelete/get/list/update文件版本管理。delete仅对 Drive 中二进制内容文件如图片、视频有效Docs/Sheets 等文件及最后一个版本不可删除。list对修订历史超大的文件可能返回不完整列表最早的修订可能被省略teamdrivescreate/get/list/update已弃用请改用drives下的同名方法4.1 files 资源文件管理核心files是最常用的资源各方法要点如下copy— 复制文件并可按 patch 语义应用任何请求中的更新create— 创建文件支持*/uploadURI 上传媒体最大文件 5,120 GB接受的 MIME 类型为*/*上传时应指定有效 MIME 类型download— 下载文件内容下载操作自创建起 24 小时内有效export— 将 Google Workspace 文档导出为指定 MIME 类型并返回字节内容导出内容限制 10 MBgenerateIds— 生成一组文件 ID可在 create/copy 请求中使用get— 按 ID 获取文件元数据或内容若提供 URL 参数altmedia响应体将包含文件内容仅对存储在 Drive 中的文件有效list— 列出用户文件接受q搜索参数。默认返回包括已删除trashed文件在内的全部文件若不需要使用trashedfalse查询参数过滤listLabels/modifyLabels— 列出文件上的标签 / 修改文件上的标签集合update— 以 patch 语义更新文件元数据、内容或两者只填充你要修改的字段部分字段如modifiedDate可能被自动变更支持*/uploadURI 上传媒体上限同上watch— 订阅文件变更通知。实战示例来自 README.md Quick Start# 列出最近 10 个文件 gws drive files list --params {pageSize: 10} # 流式分页输出文件名NDJSON gws drive files list --params {pageSize: 100} --page-all | jq -r .files[].namemultipart 上传示例README.md Advanced Usagegws drive files create --json {name: report.pdf} --upload ./report.pdfShell 技巧--params与--json的值请用单引号包裹避免 shell 解析内部双引号zsh 下含!的表达式如 Sheets 范围需改用双引号并转义内部引号。4.2 搜索与过滤q参数drives.list与files.list均接受q查询参数用于组合一个或多个搜索词。例如# 排除已删除文件 gws drive files list --params {q: trashed false, pageSize: 50} # 按名称前缀搜索 gws drive files list --params {q: name contains \Q1\, fields: files(id,name,mimeType)}注意q语法遵循 Google Drive API 的搜索表达式规范如name contains ...、mimeType ...、folderId in parents等。五、文件上传实战upload辅助命令gws drive提供了upload辅助命令用一条命令完成“自动元数据 媒体上传”无需手写files.create的 JSON 请求体详见 skills/gws-drive-upload/SKILL.md。5.1 用法与参数gws drive upload fileFlag必填默认值说明file✓—要上传的文件路径--parent——父文件夹 ID--name——目标文件名默认取源文件名5.2 示例gws drive upload ./report.pdf gws drive upload ./report.pdf --parent FOLDER_ID gws drive upload ./data.csv --name Sales Data.csv5.3 底层实现剖析upload命令由 drive.rs 实现核心逻辑如下参数解析file位置参数 1、--parent、--name三个参数通过 clap 注入命令树drive.rs文件名推断determine_filename优先采用--name否则从本地路径提取文件名组件空路径或根路径/因无文件名组件会返回校验错误drive.rs元数据构建build_metadata生成{name: ..., parents: [...]}仅当传入--parent时才附加parents数组drive.rs发现方法从 Discovery 文档的files资源中查找create方法取其声明的 OAuth scopes 完成认证drive.rs媒体上传将文件以UploadSource::File形式交给执行器MIME 类型根据文件扩展名自动推断executor.rs 的UploadSource枚举注释明确说明内容类型由文件扩展名推断可被元数据 mimeType 覆盖或显式指定--dry-run模式下跳过认证与真实上传。该实现的单元测试覆盖了文件名推断与元数据构建的全部分支显式--name优先、路径推断、非法路径报错、有/无--parent时parents字段的有无drive.rs。[!CAUTION]upload是写操作命令——执行前请与用户确认。六、输出、分页与安全加固6.1 结构化输出所有输出成功、错误、下载元数据均为结构化 JSON默认--format json可切换table/yaml/csv。结构化输出让 AI Agent 无需定制工具即可直接解析结果并驱动后续决策。6.2 分页控制Flag说明默认值--page-all自动分页每页一行 JSONNDJSON关闭--page-limit N最大抓取页数10--page-delay MS页间延迟100 ms默认分页配置见 executor.rs 的PaginationConfig实现。6.3 内容安全筛查对可能包含 PII 或注入攻击的响应可接入 Google Cloud Model Armorgws drive files get --params {fileId: ...} \ --sanitize projects/P/locations/L/templates/T相关环境变量GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE默认模板、GOOGLE_WORKSPACE_CLI_SANITIZE_MODEwarn默认 /block。七、与 Drive 相关的进阶技能与配方本仓库为 Drive 生态还配套了多份可组合的技能/配方完整索引见 docs/skills.mdskills/gws-drive-upload/SKILL.md — 本文所述的upload上传技能高级工作流配方recipe-organize-drive-folder创建文件夹结构并整理文件、recipe-email-drive-link分享文件并邮件发送链接、recipe-create-shared-drive创建共享盘并添加成员、recipe-watch-drive-changes订阅文件/文件夹变更通知、recipe-bulk-download-folder批量下载文件夹等均可在gws drive基础上直接编排执行。八、最佳实践小结先查后调任何方法调用前先gws drive --help与gws schema drive.resource.method确认必填参数与字段最小化字段about.get、comments.*等方法强制要求fields参数其余场景也建议显式声明fields以减少响应体积善用--dry-run写/删操作先本地校验符合技能文档的安全规则注意平台限制上传上限 5,120 GB、导出上限 10 MB、下载有效期 24 小时、并发权限操作不被支持、revisions 删除仅限二进制文件——这些边界条件直接决定脚本的容错设计结合 Agent 工作流配合--page-all的 NDJSON 输出与jq管道可轻松实现“列出 → 筛选 → 批量处理”的自动化链路。从gws drive files list到gws drive upload这套命令面既覆盖了 Drive v3 的完整资源模型又以 Discovery 动态构建保证了与官方 API 的同步演进——是个人自动化与 AI Agent 接入 Google Drive 的最短路径。【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gws CLI 的 Google Drive 实战指南：动态命令、资源方法与文件上传全解析
gws CLI 的 Google Drive 实战指南动态命令、资源方法与文件上传全解析【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cligwsGoogle Workspace CLI是一个从 Google Discovery Service 动态构建命令面的单文件命令行工具覆盖 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 等全部 Workspace API。本文聚焦其中的gws drive命令族你将掌握 Drive v3 全部 12 个 API 资源about、files、drives、permissions、changes、comments、revisions 等的调用语法学会用--help与gws schema自查任意方法签名并通过upload辅助命令完成带自动元数据的文件上传。文章所有命令与参数均可在本仓库对应源码与技能文档中逐一验证。一、前提先掌握 gws 的认证、全局标志与安全规则gws drive依赖 skills/gws-shared/SKILL.md 中定义的公共约定。在使用任何 Drive 命令前请先完成认证与技能安装若本机缺少gws-shared技能可运行gws generate-skills生成。1.1 安装与认证gws二进制需位于$PATH。安装方式详见 README.md包括下载预编译二进制、npm install -g googleworkspace/cli、cargo install --git ... --locked或 Nix flake。认证支持两种主流方式# 浏览器 OAuth交互式推荐本地桌面 gws auth login # 服务账号服务器到服务器无需登录 export GOOGLE_APPLICATION_CREDENTIALS/path/to/key.json认证优先级从高到低为GOOGLE_WORKSPACE_CLI_TOKEN预取访问令牌→GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE凭证文件→gws auth login加密存储的凭证 →~/.config/gws/credentials.json明文凭证。1.2 全局标志Flag说明--format FORMAT输出格式json默认、table、yaml、csv--dry-run仅在本地校验不真正调用 API--sanitize TEMPLATE通过 Model Armor 筛查响应内容1.3 CLI 通用语法与方法级标志gws service resource [sub-resource] method [flags]Flag说明--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 Key/Token 等机密执行写/删命令前必须与用户确认破坏性操作优先使用--dry-run涉及 PII 或内容安全时使用--sanitize。二、命令面从何而来Discovery 动态构建机制gws drive的每一个资源与方法并非硬编码在二进制中。其架构采用两阶段解析见 README.md 的 Architecture 一节读取argv[1]识别服务名如drive拉取该服务的 Discovery Document缓存 24 小时缓存目录为~/.config/gws/cache/见 discovery.rs依据文档中的resources与methods构建clap::Command树重新解析剩余参数认证、构造 HTTP 请求并执行。因此当 Google 新增 Drive API 端点时gws drive会自动获得新命令无需升级 CLI。与此同时drive服务还注册了一个手写的辅助命令upload——辅助命令统一以前缀命名与 Discovery 自动生成的普通方法名永不冲突Helpertrait 定义见 helpers/mod.rsget_helper将drive映射到DriveHelper见 helpers/mod.rs。三、命令自检--help与gws schema调用任何 API 方法之前先用两个命令完成“查”的工作见 skills/gws-drive/SKILL.md 的 Discovering Commands 一节# 浏览资源与方法含 upload 辅助命令 gws drive --help # 查看某个方法的必填参数、类型与默认值 gws schema drive.resource.methodgws schema的输出用于构建你的--params与--json标志。其底层实现位于 schema.rs点分路径service.resource[.subresource].method会被解析find_method沿资源树逐层下钻定位方法schema.rs随后输出httpMethod、path、parameters含type、required、location、format、default、enum、repeated、deprecated等字段、scopes、requestBody与response的内联 schema--resolve-refs会递归展开$refschema.rs。典型用法# 查看 drive.files.list 的参数与响应结构 gws schema drive.files.list # 查看 File 类型定义 gws schema drive.File四、Drive v3 资源与方法全景gws drive resource method的完整命令面覆盖以下 12 个资源。下表为所有可用方法内容继承自 skills/gws-drive/SKILL.md 的 API Resources 一节并按官方语义补充说明资源方法说明aboutget获取用户、用户 Drive 及系统能力信息。必填必须设置fields参数以精确返回所需字段accessproposalsget/list/resolve按 ID 获取、列出文件上的访问提案、批准或拒绝访问提案。注意仅审批人可list非审批人返回 403approvalsget/list获取/列出文件上的 Approvalappsget/list获取指定应用/列出用户已安装应用changesgetStartPageToken/list/watch获取起始 pageToken、列出用户或共享盘的变更、订阅用户变更通知channelsstop停止通过该 channel 监听资源变更commentscreate/delete/get/list/update文件的评论管理。除delete外create/get/list/update均必填fields参数drivescreate/get/hide/list/unhide/update共享盘管理。list接受q搜索参数filescopy/create/download/export/generateIds/get/list/listLabels/modifyLabels/update/watch文件全生命周期操作详见下文专节operationsget获取长时间运行操作的最新状态可按 API 建议的间隔轮询permissionscreate/delete/get/list/update文件或共享盘的权限管理。警告同一文件上的并发权限操作不被支持只应用最后一次更新repliescreate/delete/get/list/update评论回复管理revisionsdelete/get/list/update文件版本管理。delete仅对 Drive 中二进制内容文件如图片、视频有效Docs/Sheets 等文件及最后一个版本不可删除。list对修订历史超大的文件可能返回不完整列表最早的修订可能被省略teamdrivescreate/get/list/update已弃用请改用drives下的同名方法4.1 files 资源文件管理核心files是最常用的资源各方法要点如下copy— 复制文件并可按 patch 语义应用任何请求中的更新create— 创建文件支持*/uploadURI 上传媒体最大文件 5,120 GB接受的 MIME 类型为*/*上传时应指定有效 MIME 类型download— 下载文件内容下载操作自创建起 24 小时内有效export— 将 Google Workspace 文档导出为指定 MIME 类型并返回字节内容导出内容限制 10 MBgenerateIds— 生成一组文件 ID可在 create/copy 请求中使用get— 按 ID 获取文件元数据或内容若提供 URL 参数altmedia响应体将包含文件内容仅对存储在 Drive 中的文件有效list— 列出用户文件接受q搜索参数。默认返回包括已删除trashed文件在内的全部文件若不需要使用trashedfalse查询参数过滤listLabels/modifyLabels— 列出文件上的标签 / 修改文件上的标签集合update— 以 patch 语义更新文件元数据、内容或两者只填充你要修改的字段部分字段如modifiedDate可能被自动变更支持*/uploadURI 上传媒体上限同上watch— 订阅文件变更通知。实战示例来自 README.md Quick Start# 列出最近 10 个文件 gws drive files list --params {pageSize: 10} # 流式分页输出文件名NDJSON gws drive files list --params {pageSize: 100} --page-all | jq -r .files[].namemultipart 上传示例README.md Advanced Usagegws drive files create --json {name: report.pdf} --upload ./report.pdfShell 技巧--params与--json的值请用单引号包裹避免 shell 解析内部双引号zsh 下含!的表达式如 Sheets 范围需改用双引号并转义内部引号。4.2 搜索与过滤q参数drives.list与files.list均接受q查询参数用于组合一个或多个搜索词。例如# 排除已删除文件 gws drive files list --params {q: trashed false, pageSize: 50} # 按名称前缀搜索 gws drive files list --params {q: name contains \Q1\, fields: files(id,name,mimeType)}注意q语法遵循 Google Drive API 的搜索表达式规范如name contains ...、mimeType ...、folderId in parents等。五、文件上传实战upload辅助命令gws drive提供了upload辅助命令用一条命令完成“自动元数据 媒体上传”无需手写files.create的 JSON 请求体详见 skills/gws-drive-upload/SKILL.md。5.1 用法与参数gws drive upload fileFlag必填默认值说明file✓—要上传的文件路径--parent——父文件夹 ID--name——目标文件名默认取源文件名5.2 示例gws drive upload ./report.pdf gws drive upload ./report.pdf --parent FOLDER_ID gws drive upload ./data.csv --name Sales Data.csv5.3 底层实现剖析upload命令由 drive.rs 实现核心逻辑如下参数解析file位置参数 1、--parent、--name三个参数通过 clap 注入命令树drive.rs文件名推断determine_filename优先采用--name否则从本地路径提取文件名组件空路径或根路径/因无文件名组件会返回校验错误drive.rs元数据构建build_metadata生成{name: ..., parents: [...]}仅当传入--parent时才附加parents数组drive.rs发现方法从 Discovery 文档的files资源中查找create方法取其声明的 OAuth scopes 完成认证drive.rs媒体上传将文件以UploadSource::File形式交给执行器MIME 类型根据文件扩展名自动推断executor.rs 的UploadSource枚举注释明确说明内容类型由文件扩展名推断可被元数据 mimeType 覆盖或显式指定--dry-run模式下跳过认证与真实上传。该实现的单元测试覆盖了文件名推断与元数据构建的全部分支显式--name优先、路径推断、非法路径报错、有/无--parent时parents字段的有无drive.rs。[!CAUTION]upload是写操作命令——执行前请与用户确认。六、输出、分页与安全加固6.1 结构化输出所有输出成功、错误、下载元数据均为结构化 JSON默认--format json可切换table/yaml/csv。结构化输出让 AI Agent 无需定制工具即可直接解析结果并驱动后续决策。6.2 分页控制Flag说明默认值--page-all自动分页每页一行 JSONNDJSON关闭--page-limit N最大抓取页数10--page-delay MS页间延迟100 ms默认分页配置见 executor.rs 的PaginationConfig实现。6.3 内容安全筛查对可能包含 PII 或注入攻击的响应可接入 Google Cloud Model Armorgws drive files get --params {fileId: ...} \ --sanitize projects/P/locations/L/templates/T相关环境变量GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE默认模板、GOOGLE_WORKSPACE_CLI_SANITIZE_MODEwarn默认 /block。七、与 Drive 相关的进阶技能与配方本仓库为 Drive 生态还配套了多份可组合的技能/配方完整索引见 docs/skills.mdskills/gws-drive-upload/SKILL.md — 本文所述的upload上传技能高级工作流配方recipe-organize-drive-folder创建文件夹结构并整理文件、recipe-email-drive-link分享文件并邮件发送链接、recipe-create-shared-drive创建共享盘并添加成员、recipe-watch-drive-changes订阅文件/文件夹变更通知、recipe-bulk-download-folder批量下载文件夹等均可在gws drive基础上直接编排执行。八、最佳实践小结先查后调任何方法调用前先gws drive --help与gws schema drive.resource.method确认必填参数与字段最小化字段about.get、comments.*等方法强制要求fields参数其余场景也建议显式声明fields以减少响应体积善用--dry-run写/删操作先本地校验符合技能文档的安全规则注意平台限制上传上限 5,120 GB、导出上限 10 MB、下载有效期 24 小时、并发权限操作不被支持、revisions 删除仅限二进制文件——这些边界条件直接决定脚本的容错设计结合 Agent 工作流配合--page-all的 NDJSON 输出与jq管道可轻松实现“列出 → 筛选 → 批量处理”的自动化链路。从gws drive files list到gws drive upload这套命令面既覆盖了 Drive v3 的完整资源模型又以 Discovery 动态构建保证了与官方 API 的同步演进——是个人自动化与 AI Agent 接入 Google Drive 的最短路径。【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考