gogcli 输出契约完整指南--json 与 --plain 如何让 stdout 永远可被脚本解析【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligogcli 是一个把 Google WorkspaceGmail、Drive、Calendar 等装进终端的命令行工具。它最容易被忽视、却对自动化最重要的设计是它的输出契约只要加上--json或--plain两个全局参数gogcli的标准输出stdout就永远只会是结构化数据或稳定的 TSV 文本可以被任何脚本可靠解析。本文用最短的篇幅讲清楚这两个参数背后的完整机制。为什么普通 CLI 输出很难喂给脚本 把命令行工具接进自动化流水线时最常见的翻车点不是功能而是输出不可预期彩色高亮、进度条、提示语混在结果里jq直接解析失败提示信息打到 stdout导致重定向文件里混入垃圾文本换个终端宽度、换个 locale列对齐就变了awk脚本当场崩溃。gogcli的做法是把给人看的输出和给机器看的输出严格分开并且把规则固化在代码里而不是靠使用约定。两种机器输出模式--json 与 --plaingogcli提供两个全局输出开关定义在 internal/cmd/root.go 的根参数中参数别名 / 短写输出形态适用场景--json--machine/-j带缩进的 JSON写入 stdout接jq、yq、任何语言解析器--plain--tsv/-p稳定 TSV 纯文本无颜色、无对齐填充接awk、cut、grep两者互斥同时传入会被判定为用法错误直接以退出码 2 失败而不是被悄悄忽略。这条规则由 internal/outfmt/outfmt.go 中的FromFlags函数强制保证。最简单的用法gog --json gmail search newer_than:7d gog --plain calendar events --todaystdout 与 stderr 的硬隔离契约的核心stdout 永远可解析不是口号gogcli的契约是主数据写 stdout提示、进度、警告、诊断信息一律写 stderr。--json模式下的 JSON 由 internal/outfmt/outfmt.go 的WriteJSON统一编码保证格式稳定表格类命令在普通模式下用 tabwriter 对齐给人看切到--plain后 internal/outfmt/table.go 的WriteTable直接输出制表符分隔的裸 TSV不再做任何视觉对齐。也就是说gog ... --json out.json拿到的文件 100% 是合法 JSON2/dev/null可以安全地丢弃所有人类提示。这是输出契约里最关键的一条。用 GOG_JSON 与 GOG_PLAIN 环境变量全局固定模式 ️不想每条命令都写参数设置环境变量即可见 internal/outfmt/outfmt.go 的FromEnvexport GOG_JSON1 # 所有 gog 命令默认输出 JSON export GOG_PLAIN1 # 默认输出 TSV优先级规则很明确命令行显式参数 环境变量。在 JSON 与 TSV 同时生效时GOG_JSON胜出避免模式歧义。对 CI 脚本尤其友好在环境文件里写一次后续几百行命令都不用再想输出格式。再瘦一层--results-only 与 --select 字段投影拿到 JSON 后还嫌大两个 JSON 模式专属开关可以进一步瘦身--results-only剥掉分页令牌等信封字段只输出主结果数组--select id,subject只保留指定字段支持a.b点路径也可写作--fields、--pick、--project。gog --json --results-only --select id,subject \ gmail search newer_than:7d两者都会先解包再投影规则细节记录在 docs/automation.md 的 Machine output 一节。退出码契约不解析 stderr 也能做分支判断可解析的 stdout 只解决了一半问题另一半是状态。gogcli定义了命名退出码同样记录于 docs/automation.md脚本直接按数字分支即可退出码名称含义0ok成功2usage参数/用法错误如同时传 --json 和 --plain4auth_required凭证缺失、过期或被吊销5not_found资源不存在7rate_limited触发 API 配额限制8retryable网络超时等可重试故障if out$(gog --no-input --json drive get $id); then printf %s\n $out else case $? in 4) echo 重新登录 2 ;; 7|8) echo 稍后重试 2 ;; esac fi想程序化地读取完整退出码表gog schema --json | jq .automation.exit_codes即可。安全档案锁死输出模式自动化再保险 当gogcli由 Agent 或他人调用时还可以用**安全档案safety profile**把输出模式直接锁死。例如 safety-profiles/readonly.yaml 一类档案会把plain或json锁定为固定值此时与之冲突的命令行参数会直接报错而不会静默生效。机制实现见 internal/safetyprofile/ 与bake-safety-profile构建工具cmd/bake-safety-profile/可在编译期把策略烘焙进二进制。速查清单 ✅需求用什么让 jq 解析结果gog --json command让 awk/cut 解析结果gog --plain command整 shell 固定模式export GOG_JSON1或GOG_PLAIN1JSON 只留主结果--results-onlyJSON 只留指定字段--select a,b.c无人值守 / CI追加--no-input只读兜底追加--readonly一句话总结gogcli输出契约数据只走 stdout噪音只走 stderr格式由参数决定状态由退出码表达。掌握了这四条你的脚本就再也不会被终端输出绊倒。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gogcli 输出契约完整指南：--json 与 --plain 如何让 stdout 永远可被脚本解析
gogcli 输出契约完整指南--json 与 --plain 如何让 stdout 永远可被脚本解析【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligogcli 是一个把 Google WorkspaceGmail、Drive、Calendar 等装进终端的命令行工具。它最容易被忽视、却对自动化最重要的设计是它的输出契约只要加上--json或--plain两个全局参数gogcli的标准输出stdout就永远只会是结构化数据或稳定的 TSV 文本可以被任何脚本可靠解析。本文用最短的篇幅讲清楚这两个参数背后的完整机制。为什么普通 CLI 输出很难喂给脚本 把命令行工具接进自动化流水线时最常见的翻车点不是功能而是输出不可预期彩色高亮、进度条、提示语混在结果里jq直接解析失败提示信息打到 stdout导致重定向文件里混入垃圾文本换个终端宽度、换个 locale列对齐就变了awk脚本当场崩溃。gogcli的做法是把给人看的输出和给机器看的输出严格分开并且把规则固化在代码里而不是靠使用约定。两种机器输出模式--json 与 --plaingogcli提供两个全局输出开关定义在 internal/cmd/root.go 的根参数中参数别名 / 短写输出形态适用场景--json--machine/-j带缩进的 JSON写入 stdout接jq、yq、任何语言解析器--plain--tsv/-p稳定 TSV 纯文本无颜色、无对齐填充接awk、cut、grep两者互斥同时传入会被判定为用法错误直接以退出码 2 失败而不是被悄悄忽略。这条规则由 internal/outfmt/outfmt.go 中的FromFlags函数强制保证。最简单的用法gog --json gmail search newer_than:7d gog --plain calendar events --todaystdout 与 stderr 的硬隔离契约的核心stdout 永远可解析不是口号gogcli的契约是主数据写 stdout提示、进度、警告、诊断信息一律写 stderr。--json模式下的 JSON 由 internal/outfmt/outfmt.go 的WriteJSON统一编码保证格式稳定表格类命令在普通模式下用 tabwriter 对齐给人看切到--plain后 internal/outfmt/table.go 的WriteTable直接输出制表符分隔的裸 TSV不再做任何视觉对齐。也就是说gog ... --json out.json拿到的文件 100% 是合法 JSON2/dev/null可以安全地丢弃所有人类提示。这是输出契约里最关键的一条。用 GOG_JSON 与 GOG_PLAIN 环境变量全局固定模式 ️不想每条命令都写参数设置环境变量即可见 internal/outfmt/outfmt.go 的FromEnvexport GOG_JSON1 # 所有 gog 命令默认输出 JSON export GOG_PLAIN1 # 默认输出 TSV优先级规则很明确命令行显式参数 环境变量。在 JSON 与 TSV 同时生效时GOG_JSON胜出避免模式歧义。对 CI 脚本尤其友好在环境文件里写一次后续几百行命令都不用再想输出格式。再瘦一层--results-only 与 --select 字段投影拿到 JSON 后还嫌大两个 JSON 模式专属开关可以进一步瘦身--results-only剥掉分页令牌等信封字段只输出主结果数组--select id,subject只保留指定字段支持a.b点路径也可写作--fields、--pick、--project。gog --json --results-only --select id,subject \ gmail search newer_than:7d两者都会先解包再投影规则细节记录在 docs/automation.md 的 Machine output 一节。退出码契约不解析 stderr 也能做分支判断可解析的 stdout 只解决了一半问题另一半是状态。gogcli定义了命名退出码同样记录于 docs/automation.md脚本直接按数字分支即可退出码名称含义0ok成功2usage参数/用法错误如同时传 --json 和 --plain4auth_required凭证缺失、过期或被吊销5not_found资源不存在7rate_limited触发 API 配额限制8retryable网络超时等可重试故障if out$(gog --no-input --json drive get $id); then printf %s\n $out else case $? in 4) echo 重新登录 2 ;; 7|8) echo 稍后重试 2 ;; esac fi想程序化地读取完整退出码表gog schema --json | jq .automation.exit_codes即可。安全档案锁死输出模式自动化再保险 当gogcli由 Agent 或他人调用时还可以用**安全档案safety profile**把输出模式直接锁死。例如 safety-profiles/readonly.yaml 一类档案会把plain或json锁定为固定值此时与之冲突的命令行参数会直接报错而不会静默生效。机制实现见 internal/safetyprofile/ 与bake-safety-profile构建工具cmd/bake-safety-profile/可在编译期把策略烘焙进二进制。速查清单 ✅需求用什么让 jq 解析结果gog --json command让 awk/cut 解析结果gog --plain command整 shell 固定模式export GOG_JSON1或GOG_PLAIN1JSON 只留主结果--results-onlyJSON 只留指定字段--select a,b.c无人值守 / CI追加--no-input只读兜底追加--readonly一句话总结gogcli输出契约数据只走 stdout噪音只走 stderr格式由参数决定状态由退出码表达。掌握了这四条你的脚本就再也不会被终端输出绊倒。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考