gogcli 的gog drive drives命令在终端中列出与检索共享云端硬盘Team Drives完整指南【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog drive drives是 Google Workspace 命令行工具 gogcli 中用于列出当前账号可访问的共享云端硬盘Shared Drives即原 Team Drives的核心命令。本文以该命令的官方文档为骨架结合仓库源码深入讲解其用法、全部参数语义、分页机制与底层 Drive v3 API 调用链帮助你快速上手既能交互式浏览共享盘列表也能在脚本与 LLM 工作流中以 JSON/TSV 输出消费数据并正确衔接gog drive search --drive等下游操作。命令概览与定位gog drive drives隶属于 gog drive 命令族位于 Google Drive 权限体系中的共享盘枚举环节。它的核心职责是列出你有权访问的所有共享云端硬盘Shared Drives也就是传统概念中的 Team Drives——由组织创建、成员共享、独立于个人 My Drive 的团队级存储空间。在仓库源码中该命令注册于 internal/cmd/drive.goDrives DriveDrivesCmd cmd: name:drives help:List shared drives (Team Drives)其完整实现位于 internal/cmd/drive_drives.go是整个 Drive 命令族中面向共享盘元数据管理如gog drive search --drive、gog drive ls --all-drives的基础入口。基本用法gog drive (drv) drives [flags]drv是drive的别名因此以下三种写法等价gog drive drives gog drv drives gog drive drives --all不带任何参数时命令默认返回最多 100 条共享盘记录对应 Drive API 的单页上限并在终端以表格形式输出。命令专属参数FlagTypeDefaultHelp--max--limitint64100Max results (max allowed: 100)--page--cursorstringPage token--all--all-pages--allpagesboolFetch all pages--fail-empty--non-empty--require-resultsboolExit with code 3 if no results-q--querystringSearch query for filtering shared drives这五个参数直接映射到 internal/cmd/drive_drives.go 中的结构体字段type DriveDrivesCmd struct { Max int64 name:max aliases:limit help:Max results (max allowed: 100) default:100 Page string name:page aliases:cursor help:Page token All bool name:all aliases:all-pages,allpages help:Fetch all pages FailEmpty bool name:fail-empty aliases:non-empty,require-results help:Exit with code 3 if no results Query string name:query short:q help:Search query for filtering shared drives }--max/--limit控制返回条数单页最多返回 100 条。若传入--max 0或负数命令会直接报错退出源码中检查if c.Max 0并返回usage(max must be 0)。注意 Drive v3 API 的pageSize上限就是 100因此即便不设限制单次请求也不会超过 100 条更多数据需要配合分页参数获取。--page/--cursor游标续页分页游标由服务端返回的nextPageToken提供。在脚本中你通常会先跑一次拿到 token再把它作为--page传入获取下一页形成循环翻页。对应源码中if page : strings.TrimSpace(pageToken); page ! { call call.PageToken(page) }--all/--all-pages/--allpages一键拉全量设置后命令会自动循环请求直到nextPageToken为空一次性返回全部共享盘。底层复用 internal/cmd/paged_list_helpers.go 的泛型分页收集函数loadPagedItems当all true时调用collectAllPages持续翻页否则只请求传入的起始页。表格模式下若还有剩余页命令会打印提示--all/--all-pages以便你补拉全量。-q/--query按名称过滤传入的查询字符串会被直接透传给 Drive v3 API 的q参数见源码call.Q(q)例如按名称关键字过滤共享盘。该参数是搜索共享云端硬盘场景的关键入口。--fail-empty/--require-results无结果即报错当结果为空时命令退出码为3可用于 CI 脚本中断言必须存在某个共享盘该行为同时作用于表格与 JSON 两种输出模式。通用全局参数以下参数为 gogcli 全命令族共享对gog drive drives同样生效FlagTypeDefaultHelp--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)-a--account--acctstringAccount email, alias, or auto for authenticated Google API commands--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never--disable-commandsstringComma-separated list of disabled commands; dot paths allowed-n--dry-run--dryrun--noop--previewboolDo not make changes; print intended actions and exit successfully--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children--fail-empty--non-empty--require-resultsboolExit with code 3 if no results-y--force--assume-yes--yesboolSkip confirmations for destructive commands--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)-h--helpkong.helpFlagShow context-sensitive help.--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)-j--json--machineboolfalseOutput JSON to stdout (best for scripting)--no-input--non-interactive--noninteractiveboolNever prompt; fail instead (useful for CI)-p--plain--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select--pick--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands.-v--verboseboolEnable verbose logging--versionkong.VersionFlagPrint version and exit--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers其中与本文命令强相关的几个要点-j/--json切换到 JSON 输出便于脚本与 LLM 消费。命令会输出包含drives数组与nextPageToken的结构化载荷源码见 internal/cmd/drive_drives.go可用--results-only只保留drives主体、用--select挑选字段。-p/--plain/--tsv输出稳定的 TSV 文本无颜色适合管道处理。-a/--account指定账号邮箱、别名或auto用于多账号场景不指定时使用默认认证账号。--readonly运行时拦截所有写操作请求列表类命令天然只读可放心与--readonly搭配用于审计脚本。输出格式与示例默认表格输出$ gog drive drives ID NAME CREATED 0AKwxxxxx Marketing Team Drive 2023-04-12T08:15:30Z 0ALaxxxxx Engineering Shared 2022-11-03T14:02:11Z表格包含三列ID共享盘唯一标识Drive 中称为 driveId、NAME共享盘名称、CREATED创建时间。这一列结构直接对应源码中的输出逻辑与 API 字段掩码fmt.Fprintln(w, ID\tNAME\tCREATED) ... call : svc.Drives.List(). PageSize(c.Max). Fields(nextPageToken, drives(id, name, createdTime))可见底层请求只拉取id、name、createdTime三个字段避免不必要的数据传输这也是表格输出列来源的直接证据。过滤查询# 按名称关键字过滤共享盘 gog drive drives -q name contains Marketing拉取全量# 一次性获取所有可访问的共享盘 gog drive drives --allJSON 输出脚本 / LLM 场景$ gog drive drives -j {drives:[{id:0AKwxxxxx,name:Marketing Team Drive,createdTime:2023-04-12T08:15:30Z}],nextPageToken:}# 只输出主体数组去掉 nextPageToken 等信封字段 gog drive drives -j --results-only # 只挑选指定字段支持点路径 gog drive drives -j --select id,nameTSV 输出管道处理gog drive drives -p | cut -f2 # 只取共享盘名称CI 断言# 期望至少存在一个共享盘否则退出码 3 gog drive drives --fail-empty底层实现原理从命令到 Drive v3 APIgog drive drives的执行链路非常清晰可以在 internal/cmd/drive_drives.go 中逐段对应服务初始化requireDriveService(ctx, flags)根据账号与 OAuth 凭据创建 Google Drive v3 服务客户端该辅助函数定义于 internal/cmd/service_helpers.go实际委托给requireGoogleService完成账号解析、token 刷新与 API 客户端构建。构造请求svc.Drives.List()指定PageSize(c.Max)与字段掩码Fields(nextPageToken, drives(id, name, createdTime))。应用过滤与分页非空--page透传为PageToken非空--query透传为Q(q)。统一分页框架通过 internal/cmd/paged_list_helpers.go 的泛型函数loadPagedItems决定只取当前页--all未开启还是循环收集所有页--all开启。这也是 gogcli 中所有可枚举资源命令如列表、日志类命令共享的分页基础设施从源码结构看属于全局统一的分页设计。输出分流JSON 模式调用writePagedJSONResult输出{drives, nextPageToken}信封并支持--fail-empty退出码否则以表格形式输出 ID/NAME/CREATED空结果时打印No shared drives并同样可触发退出码 3。值得注意的是gog drive drives本身不携带--all-drives或--drive参数——这两个参数属于gog drive ls/gog drive search等文件级命令见 internal/cmd/drive.go用于决定是否把共享盘纳入文件搜索范围。gog drive drives的输出driveId正是为这些命令提供入参例如gog drive search --drive driveId ...可把搜索范围精确限定在某个共享盘内其源码帮助文本也明确写道Pass the driveId from gog drive drives。与其他命令的衔接gog drive search --drive driveId把全文搜索限定到某个共享盘corporadrive。gog drive ls --all-drives/--no-all-drives控制文件列举是否包含共享盘默认为包含。gog drive raw以无损 JSON 输出单个文件的完整 API 响应可用于对共享盘内文件做二次分析。你可以先用gog drive drives -j --select id,name快速拿到共享盘清单再把 driveId 喂给gog drive search做定点检索形成枚举共享盘 → 定位文件的完整链路。适用前提与限制该命令依赖 Google Drive v3 API需要账号已通过gog auth完成 OAuth 认证可用gog auth status检查。只能列出你被授予访问权限的共享盘个人 My Drive 不属于 Shared Drive不在结果中。单页上限 100 条为 Google API 硬限制超出部分必须用--page翻页或--all全量拉取。空结果时默认退出码为 0只有在显式指定--fail-empty时才以退出码 3 表示无结果请勿在脚本中混淆。参考命令文档docs/commands/gog-drive-drives.md父命令文档gog drive命令索引Command index实现源码internal/cmd/drive_drives.go命令注册internal/cmd/drive.go分页基础设施internal/cmd/paged_list_helpers.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考