gogcli 实战指南用gog groups list在终端查询你所属的 Google Workspace 群组【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog groups list是 gogcliGoogle Workspace CLI中面向 Cloud Identity Groups 的只读查询命令用于列出当前账户所属的所有群组并区分直接direct与间接indirect成员关系。本文以 docs/commands/gog-groups-list.md 的官方命令文档为骨架结合 internal/cmd/groups.go 的源码实现讲清它的适用前提、全部命令行参数、两种输出形态的字段细节以及底层调用的 Cloud Identity API 查询逻辑与常见错误处理。命令定位与适用前提groups命令组在 gogcli 中的官方定位是 Cloud Identity Groups (Workspace only)见 docs/commands/gog-groups.md。也就是说它依赖 Google 的Cloud Identity API v1只适用于 Google Workspace / Cloud Identity 账户个人消费类账户gmail.com / googlemail.com不受支持。这个限制不是写在文档里的一句提醒而是在源码中被硬性校验的。从 internal/cmd/groups.go 可以看到固定的错误文案groupsWorkspaceRequiredMessage Cloud Identity Groups require a Google Workspace/Cloud Identity account; consumer accounts (gmail.com/googlemail.com) are not supported.requireGroupsAccount在执行前会做两层检查见 internal/cmd/groups.go#L129-L141账户必须显式指定当认证模式为直传 access token或ADCApplication Default Credentials时占位账户无法确定身份命令会直接报 usage 错误要求你显式传入--account workspace-email拒绝消费账户isConsumerAccount实现见 internal/cmd/account_helpers.go通过判断邮箱后缀是否为gmail.com/googlemail.com来识别消费账户命中即返回权限拒绝错误。因此在 CI 或服务账户场景中运行该命令前先确认你的账户是 Workspace 域名邮箱并配好--account参数。用法与完整参数gog groups (group) list (ls) [flags]list带有ls别名源码中声明为cmd: name:list aliases:ls见 internal/cmd/groups.go#L30。参数分为命令专属与全局两类前者定义在GroupsListCmd结构体上后者是所有 gog 命令共享的根级 flags。命令专属 FlagsFlag类型默认值说明--max--limitint64100单页最大返回条数必须大于 0否则报 max must be 0--page--cursorstring页令牌从上一页 JSON 输出中的nextPageToken取得--all--all-pages--allpagesbool自动翻完所有分页--fail-empty--non-empty--require-resultsbool无结果时以退出码 3 结束适合脚本/CI 判空以上四个参数的 kong 标签声明见 internal/cmd/groups.go#L34-L39。注意--max控制的是单次 API 调用的 page size不是总条数上限要拿全量结果请用--all。全局 Flags与所有 gog 命令共享Flag类型默认值说明--access-tokenstring直接使用提供的 access token绕过本地存储的 refresh tokentoken 约 1 小时过期-a/--account/--acctstring指定账户邮箱、别名或 auto用于已认证的 Google API 命令--clientstringOAuth 客户端名选择对应的存储凭据 token 桶--colorstringauto彩色输出auto|always|never--disable-commandsstring禁用命令的逗号分隔列表支持点路径--enable-commandsstring仅允许的命令前缀列表支持点路径可收窄 CLI 能力面--enable-commands-exactstring仅允许的精确命令列表父命令不会连带启用子命令-n/--dry-run/--dryrun/--noop/--previewbool不做任何变更仅打印预期动作并成功退出-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作agent 安全开关--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse以 JSON 输出到 stdout最适合脚本处理--no-input/--non-interactive/--noninteractivebool绝不交互式提问失败即报错适合 CI-p/--plain/--tsvboolfalse输出稳定、可解析的纯文本TSV无颜色--quota-projectstring计费用 GCP 项目 ID以X-Goog-User-Project头发送部分 API 在--access-token或 ADC 模式下需要--readonlyboolfalse运行时阻止一切写操作请求auth add时也会只申请只读 OAuth scope--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等 envelope 字段--select/--pick/--projectstringJSON 模式下按逗号分隔的点路径挑选字段best-effort-v/--verbosebool开启详细日志--version打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将抓取到的文本字段包裹在外部不可信内容标记内输出格式详解表格输出默认Run方法在默认模式下写出一张三列表格见 internal/cmd/groups.go#L112-L126GROUP NAME RELATION engcompany.com Engineering direct platformcompany.com Platform indirect三列含义GROUP群组 IDm.GroupKey.Id对讨论型群组即群邮箱NAME显示名DisplayNameRELATION成员关系类型由getRelationType把 API 返回的DIRECT映射为direct、INDIRECT映射为indirect未知值原样透传见 internal/cmd/groups.go#L220-L229。若还有下一页且未指定--all会打印分页提示建议追加--all/--all-pages。没有任何群组时输出No groups found此时若带了--fail-empty进程以退出码 3 结束逻辑见 internal/cmd/paging.go 的failEmptyExit。JSON 输出-j加-j后输出结构为{ groups: [ { groupName: engcompany.com, displayName: Engineering, role: direct } ], nextPageToken: ... }源码中对应outfmt.WriteJSON的写入逻辑见 internal/cmd/groups.go#L78-L105groups数组每项固定包含groupNamedisplayName与role在 API 未返回时会被omitempty省略顶层还带nextPageToken供--page续传。配合--results-only可去掉 envelope 字段配合--select可只保留需要的点路径字段——对 Agent/LLM 场景-j --results-only是最省 token 的组合。源码级原理一条 SearchTransitiveGroups 查询gog groups list的实现核心只有一处 API 调用见 internal/cmd/groups.go#L56-L71// 使用 groups/- 作为 parent跨全部群组搜索 call : svc.Groups.Memberships.SearchTransitiveGroups(groups/-). Query(searchTransitiveGroupsQuery(account)). PageSize(c.Max)关键点有两个groups/-通配 parent不是先列出所有群组再逐个查成员而是以groups/-作为搜索根一次性做成员关系搜索API 开销显著更低查询语句同时过滤成员与群类型searchTransitiveGroupsQuery见 internal/cmd/groups.go#L209-L217生成的查询为member_key_id 你的邮箱 ( cloudidentity.googleapis.com/groups.discussion_forum in labels || cloudidentity.googleapis.com/groups.dynamic in labels )即只返回**标签为 discussion_forum讨论论坛群或 dynamic动态群**的群组且要求你的邮箱是它们的含嵌套传递的成员。账号邮箱中的单引号会被转义→\避免查询注入。这也解释了为什么个人 Gmail 里没有群组概念——Cloud Identity 的群组模型本身就是 Workspace 域的组织能力。分页由通用的loadPagedItems泛型辅助函数完成internal/cmd/paged_list_helpers.go传入--page起始令牌与--all开关函数负责循环拉取直到没有nextPageToken。服务装配与错误处理Cloud Identity 客户端不是裸建而是走统一的运行时服务注册cloudIdentityServiceinternal/cmd/runtime_services.go#L249-L255从 runtime 取Services.CloudIdentity(ctx, account)构造器按账户解析凭据用户 OAuth、直传 token 或 ADC后返回*cloudidentity.Service。错误路径则由wrapCloudIdentityErrorinternal/cmd/groups.go#L168-L207统一包装覆盖三类高频故障错误特征gogcli 的处理accessNotConfigured/ Cloud Identity API has not been used提示该 API 未在项目中启用并给出启用入口insufficientPermissions/ 认证范围不足按认证模式分别提示直传 token 与 ADC 主体需具备https://www.googleapis.com/auth/cloud-identity.groups.readonly权限用户 OAuth 凭据不支持此路径建议改用gog auth service-account set email --key service-account.json的委托服务账户模式消费账户 badRequest回落到 仅 Workspace 账户可用 的统一错误文案从这套错误包装可以看出该命令的认证方式适配边界常规 Workspace 用户的 OAuth 登录、直传 access token、ADC 三种模式都支持但后两者必须显式--account纯用户 OAuth 在权限不足时无法自愈需要转向委托服务账户。实战用法示例以下示例基于文档与源码实际支持的参数组合按场景给出# 基本用法列出当前账户所属群组默认最多 100 条 gog groups list # 用 ls 别名 指定 Workspace 账户 gog groups ls -a youcompany.com # 脚本场景JSON 输出 只要主结果便于 jq 处理 gog groups list -j --results-only | jq -r .groups[].groupName # 翻页先取第一页再带 --page 续传 gog groups list -j --max 50 gog groups list -j --max 50 --page nextPageToken # CI 场景拉全量 无结果即失败退出码 3 gog groups list --all --no-input --fail-empty # 直传 tokenADC 模式下必须显式 --account gog groups list --access-token token --account youcompany.com --readonly几点提醒--max 0或负数会被拒绝max must be 0-pTSV 输出与-j是两种不同的机器可读形态TSV 列即GROUP NAME RELATION且单元格内的制表符会被sanitizeTab清理--readonly对这条只读命令影响不大但保留它可以让 gogcli 在运行时统一拦截任何意外写请求作为防御性习惯是安全的。关联命令groups命令组下另有 gog groups members接受群邮箱作为位置参数如engineeringcompany.com先通过Groups.Lookup解析群资源名再分页列出成员的EMAIL ROLE TYPE角色按 OWNER MANAGER MEMBER 取最高者。两者的组合用法先用groups list -j拿到群 ID再对感兴趣的群跑groups members展开成员即可完成一次纯 CLI 的 Workspace 群组盘点。更完整的命令索引见 docs/commands/README.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gogcli 实战指南：用 `gog groups list` 在终端查询你所属的 Google Workspace 群组
gogcli 实战指南用gog groups list在终端查询你所属的 Google Workspace 群组【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog groups list是 gogcliGoogle Workspace CLI中面向 Cloud Identity Groups 的只读查询命令用于列出当前账户所属的所有群组并区分直接direct与间接indirect成员关系。本文以 docs/commands/gog-groups-list.md 的官方命令文档为骨架结合 internal/cmd/groups.go 的源码实现讲清它的适用前提、全部命令行参数、两种输出形态的字段细节以及底层调用的 Cloud Identity API 查询逻辑与常见错误处理。命令定位与适用前提groups命令组在 gogcli 中的官方定位是 Cloud Identity Groups (Workspace only)见 docs/commands/gog-groups.md。也就是说它依赖 Google 的Cloud Identity API v1只适用于 Google Workspace / Cloud Identity 账户个人消费类账户gmail.com / googlemail.com不受支持。这个限制不是写在文档里的一句提醒而是在源码中被硬性校验的。从 internal/cmd/groups.go 可以看到固定的错误文案groupsWorkspaceRequiredMessage Cloud Identity Groups require a Google Workspace/Cloud Identity account; consumer accounts (gmail.com/googlemail.com) are not supported.requireGroupsAccount在执行前会做两层检查见 internal/cmd/groups.go#L129-L141账户必须显式指定当认证模式为直传 access token或ADCApplication Default Credentials时占位账户无法确定身份命令会直接报 usage 错误要求你显式传入--account workspace-email拒绝消费账户isConsumerAccount实现见 internal/cmd/account_helpers.go通过判断邮箱后缀是否为gmail.com/googlemail.com来识别消费账户命中即返回权限拒绝错误。因此在 CI 或服务账户场景中运行该命令前先确认你的账户是 Workspace 域名邮箱并配好--account参数。用法与完整参数gog groups (group) list (ls) [flags]list带有ls别名源码中声明为cmd: name:list aliases:ls见 internal/cmd/groups.go#L30。参数分为命令专属与全局两类前者定义在GroupsListCmd结构体上后者是所有 gog 命令共享的根级 flags。命令专属 FlagsFlag类型默认值说明--max--limitint64100单页最大返回条数必须大于 0否则报 max must be 0--page--cursorstring页令牌从上一页 JSON 输出中的nextPageToken取得--all--all-pages--allpagesbool自动翻完所有分页--fail-empty--non-empty--require-resultsbool无结果时以退出码 3 结束适合脚本/CI 判空以上四个参数的 kong 标签声明见 internal/cmd/groups.go#L34-L39。注意--max控制的是单次 API 调用的 page size不是总条数上限要拿全量结果请用--all。全局 Flags与所有 gog 命令共享Flag类型默认值说明--access-tokenstring直接使用提供的 access token绕过本地存储的 refresh tokentoken 约 1 小时过期-a/--account/--acctstring指定账户邮箱、别名或 auto用于已认证的 Google API 命令--clientstringOAuth 客户端名选择对应的存储凭据 token 桶--colorstringauto彩色输出auto|always|never--disable-commandsstring禁用命令的逗号分隔列表支持点路径--enable-commandsstring仅允许的命令前缀列表支持点路径可收窄 CLI 能力面--enable-commands-exactstring仅允许的精确命令列表父命令不会连带启用子命令-n/--dry-run/--dryrun/--noop/--previewbool不做任何变更仅打印预期动作并成功退出-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作agent 安全开关--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse以 JSON 输出到 stdout最适合脚本处理--no-input/--non-interactive/--noninteractivebool绝不交互式提问失败即报错适合 CI-p/--plain/--tsvboolfalse输出稳定、可解析的纯文本TSV无颜色--quota-projectstring计费用 GCP 项目 ID以X-Goog-User-Project头发送部分 API 在--access-token或 ADC 模式下需要--readonlyboolfalse运行时阻止一切写操作请求auth add时也会只申请只读 OAuth scope--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等 envelope 字段--select/--pick/--projectstringJSON 模式下按逗号分隔的点路径挑选字段best-effort-v/--verbosebool开启详细日志--version打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将抓取到的文本字段包裹在外部不可信内容标记内输出格式详解表格输出默认Run方法在默认模式下写出一张三列表格见 internal/cmd/groups.go#L112-L126GROUP NAME RELATION engcompany.com Engineering direct platformcompany.com Platform indirect三列含义GROUP群组 IDm.GroupKey.Id对讨论型群组即群邮箱NAME显示名DisplayNameRELATION成员关系类型由getRelationType把 API 返回的DIRECT映射为direct、INDIRECT映射为indirect未知值原样透传见 internal/cmd/groups.go#L220-L229。若还有下一页且未指定--all会打印分页提示建议追加--all/--all-pages。没有任何群组时输出No groups found此时若带了--fail-empty进程以退出码 3 结束逻辑见 internal/cmd/paging.go 的failEmptyExit。JSON 输出-j加-j后输出结构为{ groups: [ { groupName: engcompany.com, displayName: Engineering, role: direct } ], nextPageToken: ... }源码中对应outfmt.WriteJSON的写入逻辑见 internal/cmd/groups.go#L78-L105groups数组每项固定包含groupNamedisplayName与role在 API 未返回时会被omitempty省略顶层还带nextPageToken供--page续传。配合--results-only可去掉 envelope 字段配合--select可只保留需要的点路径字段——对 Agent/LLM 场景-j --results-only是最省 token 的组合。源码级原理一条 SearchTransitiveGroups 查询gog groups list的实现核心只有一处 API 调用见 internal/cmd/groups.go#L56-L71// 使用 groups/- 作为 parent跨全部群组搜索 call : svc.Groups.Memberships.SearchTransitiveGroups(groups/-). Query(searchTransitiveGroupsQuery(account)). PageSize(c.Max)关键点有两个groups/-通配 parent不是先列出所有群组再逐个查成员而是以groups/-作为搜索根一次性做成员关系搜索API 开销显著更低查询语句同时过滤成员与群类型searchTransitiveGroupsQuery见 internal/cmd/groups.go#L209-L217生成的查询为member_key_id 你的邮箱 ( cloudidentity.googleapis.com/groups.discussion_forum in labels || cloudidentity.googleapis.com/groups.dynamic in labels )即只返回**标签为 discussion_forum讨论论坛群或 dynamic动态群**的群组且要求你的邮箱是它们的含嵌套传递的成员。账号邮箱中的单引号会被转义→\避免查询注入。这也解释了为什么个人 Gmail 里没有群组概念——Cloud Identity 的群组模型本身就是 Workspace 域的组织能力。分页由通用的loadPagedItems泛型辅助函数完成internal/cmd/paged_list_helpers.go传入--page起始令牌与--all开关函数负责循环拉取直到没有nextPageToken。服务装配与错误处理Cloud Identity 客户端不是裸建而是走统一的运行时服务注册cloudIdentityServiceinternal/cmd/runtime_services.go#L249-L255从 runtime 取Services.CloudIdentity(ctx, account)构造器按账户解析凭据用户 OAuth、直传 token 或 ADC后返回*cloudidentity.Service。错误路径则由wrapCloudIdentityErrorinternal/cmd/groups.go#L168-L207统一包装覆盖三类高频故障错误特征gogcli 的处理accessNotConfigured/ Cloud Identity API has not been used提示该 API 未在项目中启用并给出启用入口insufficientPermissions/ 认证范围不足按认证模式分别提示直传 token 与 ADC 主体需具备https://www.googleapis.com/auth/cloud-identity.groups.readonly权限用户 OAuth 凭据不支持此路径建议改用gog auth service-account set email --key service-account.json的委托服务账户模式消费账户 badRequest回落到 仅 Workspace 账户可用 的统一错误文案从这套错误包装可以看出该命令的认证方式适配边界常规 Workspace 用户的 OAuth 登录、直传 access token、ADC 三种模式都支持但后两者必须显式--account纯用户 OAuth 在权限不足时无法自愈需要转向委托服务账户。实战用法示例以下示例基于文档与源码实际支持的参数组合按场景给出# 基本用法列出当前账户所属群组默认最多 100 条 gog groups list # 用 ls 别名 指定 Workspace 账户 gog groups ls -a youcompany.com # 脚本场景JSON 输出 只要主结果便于 jq 处理 gog groups list -j --results-only | jq -r .groups[].groupName # 翻页先取第一页再带 --page 续传 gog groups list -j --max 50 gog groups list -j --max 50 --page nextPageToken # CI 场景拉全量 无结果即失败退出码 3 gog groups list --all --no-input --fail-empty # 直传 tokenADC 模式下必须显式 --account gog groups list --access-token token --account youcompany.com --readonly几点提醒--max 0或负数会被拒绝max must be 0-pTSV 输出与-j是两种不同的机器可读形态TSV 列即GROUP NAME RELATION且单元格内的制表符会被sanitizeTab清理--readonly对这条只读命令影响不大但保留它可以让 gogcli 在运行时统一拦截任何意外写请求作为防御性习惯是安全的。关联命令groups命令组下另有 gog groups members接受群邮箱作为位置参数如engineeringcompany.com先通过Groups.Lookup解析群资源名再分页列出成员的EMAIL ROLE TYPE角色按 OWNER MANAGER MEMBER 取最高者。两者的组合用法先用groups list -j拿到群 ID再对感兴趣的群跑groups members展开成员即可完成一次纯 CLI 的 Workspace 群组盘点。更完整的命令索引见 docs/commands/README.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考