gogcli 的 gog gmail 命令族详解:22 个子命令、公共参数体系与 Agent 安全防护机制-平芜编程栈

gogcli 的 gog gmail 命令族详解:22 个子命令、公共参数体系与 Agent 安全防护机制

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

gog gmail（别名mail、email）是 gogcli 中覆盖 Gmail 日常操作的核心命令族:从搜索、读取、标签整理到发信、草稿、自动回复与打开追踪,以及设置管理全部收拢在这一个命令树下。本文以 docs/commands/gog-gmail.md 这份命令参考为骨架,结合internal/cmd/下的真实源码,讲清每个子命令的职责分组、全部公共参数的含义,以及 gogcli 如何通过--gmail-no-send、--enable-commands-exact等机制让 Gmail 操作可以被 Agent 安全地自动化。读完你可以直接用命令行完成收发邮件、整理邮箱、批量处理与 CI/Agent 场景下的最小权限控制。

命令入口与文档生成方式

该文档页头部明确标注:Generated from gog schema --json. Do not edit this page by hand; run make docs-commands。也就是说gog gmail的完整用法可以直接通过 schema 命令机器化获取:

gog schema gmail search --json

基本用法形式为:

gog gmail (mail,email) <command> [flags]

其中mail、email是gmail的等价别名,这在命令注册的源码中可以直接看到——internal/cmd/gmail.go 中整个命令树以 kong 标签方式声明。

子命令全景:22 个子命令及其分组

参考文档 gog-gmail.md 列出了gog gmail下的 22 个子命令。按源码 internal/cmd/gmail.go 中GmailCmd结构体的group标签,这些子命令实际被组织为Read(读取)、Organize(整理)、Write(写)、Admin(管理)四大组:

Read 组:搜索与读取

gog gmail archive - Archive messages or explicit threads (remove from inbox)
gog gmail attachment - Download a single attachment
gog gmail autoreply - Reply once to matching messages
gog gmail batch - Batch operations (permanent delete requires broader Gmail scope; use gmail trash for normal trashing)
gog gmail drafts - Draft operations
gog gmail forward - Forward a message to new recipients
gog gmail get - Get a message (full|metadata|raw)
gog gmail history - Gmail history
gog gmail import - Import an RFC822/EML message into Gmail
gog gmail labels - Label operations
gog gmail mark-read - Mark messages as read
gog gmail messages - Message operations
gog gmail raw - Dump raw Gmail API response as JSON (Users.Messages.Get; lossless; for scripting and LLM consumption)
gog gmail reply - Reply to a message
gog gmail reply-all - Reply to all message participants
gog gmail search - Search threads using Gmail query syntax
gog gmail send - Send an email
gog gmail settings - Settings and admin
gog gmail thread - Thread operations (get, modify)
gog gmail track - Email open tracking
gog gmail trash - Move messages to trash
gog gmail unread - Mark messages as unread
gog gmail url - Print Gmail web URLs for threads

从源码看分组、别名与隐藏命令

internal/cmd/gmail.go 的GmailCmd结构体是这份列表的实现来源,源码中还能看到一些文档页面未强调的细节:

别名体系:几乎每个子命令都挂了别名,方便不同习惯的用户或 Agent。例如search同时是find,query,ls,list的别名,messages是message,msg,msgs,thread是threads,read,mark-read是read-messages,trash相关操作与unread互为mark-unread等。
四大操作组:源码用group:"Read"/group:"Organize"/group:"Write"/group:"Admin"显式分组:
- Read:search、messages、thread、get、raw、attachment、url、history
- Organize:labels、batch、archive、mark-read、unread、trash
- Write:send、import、reply、reply-all、forward、autoreply、track、drafts
- Admin:settings
settings 下的二级命令树:GmailSettingsCmd进一步挂载了filters、delegates、forwarding、autoforward、sendas、vacation、watch七个子命令(见 internal/cmd/gmail.go 第 40-48 行)。值得注意的是源码中GmailCmd还声明了watch、autoforward、delegates、filters、forwarding、sendas、vacation这几个带hidden:""标签的快捷入口,即它们可通过gog gmail settings <cmd>作为一级隐藏别名直达,而不必走二级路径。
drafts 子树:gog gmail drafts下还有create、delete、forward、get、list、reply、reply-all、send、update九个叶子命令(见 docs/commands/gog-gmail-drafts.md),其中 delete 明确标注为不可恢复的永久删除。

公共参数(Flags)完整说明

以下参数表完整继承自 docs/commands/gog-gmail.md,是gog gmail及其所有子命令共享的根级参数:

Flag	Type	Default	Help
`--access-token`	`string`	Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h)
`-a` `--account` `--acct`	`string`	Account email, alias, or auto for authenticated Google API commands
`--client`	`string`	OAuth client name (selects stored credentials + token bucket)
`--color`	`string`	auto	Color output: auto\|always\|never
`--disable-commands`	`string`	Comma-separated list of disabled commands; dot paths allowed
`-n` `--dry-run` `--dryrun` `--noop` `--preview`	`bool`	Do not make changes; print intended actions and exit successfully
`--enable-commands`	`string`	Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)
`--enable-commands-exact`	`string`	Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children
`-y` `--force` `--assume-yes` `--yes`	`bool`	Skip confirmations for destructive commands
`--gmail-no-send`	`bool`	false	Block Gmail send operations (agent safety)
`-h` `--help`	`kong.helpFlag`	Show context-sensitive help.
`--home`	`string`	Override gogcli config/data/state/cache root (equivalent to GOG_HOME)
`-j` `--json` `--machine`	`bool`	false	Output JSON to stdout (best for scripting)
`--no-input` `--non-interactive` `--noninteractive`	`bool`	Never prompt; fail instead (useful for CI)
`-p` `--plain` `--tsv`	`bool`	false	Output stable, parseable text to stdout (TSV; no colors)
`--quota-project`	`string`	Google Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)
`--readonly`	`bool`	false	Block mutating API requests at runtime; auth add also requests read-only OAuth scopes
`--results-only`	`bool`	In JSON mode, emit only the primary result (drops envelope fields like nextPageToken)
`--select` `--pick` `--project`	`string`	In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands.
`-v` `--verbose`	`bool`	Enable verbose logging
`--version`	`kong.VersionFlag`	Print version and exit
`--wrap-untrusted`	`bool`	false	In JSON/raw output, wrap fetched text fields in external untrusted-content markers

按用途可以归纳为四类:

账户与凭证:--account(支持邮箱、别名或auto)、--client(选择已存的 OAuth 客户端凭证与 token 桶)、--access-token(直接用一次性 access token,绕过本地 refresh token,约 1 小时过期)、--quota-project(以X-Goog-User-Project头计费,配合--access-token或 ADC 使用)、--home(覆盖配置/数据根目录,等价于GOG_HOME)。
输出与脚本化:--json(机器可读 JSON)、--plain/--tsv(稳定可解析的 TSV 文本)、--results-only(JSON 模式下去掉信封字段如nextPageToken)、--select(按点路径挑选字段)、--color。
安全护栏:--gmail-no-send、--readonly、--enable-commands/--enable-commands-exact/--disable-commands、--no-input、-n --dry-run。
交互确认:-y --force(跳过破坏性命令确认)。

源码纵深:no-send 护栏是如何拦截发信的

--gmail-no-send是 Agent 场景的核心安全参数,它的实现值得展开。internal/cmd/gmail_no_send.go 中的enforceGmailNoSend在三层依次设防:

命令行层:命中发信路径且传入--gmail-no-send时直接报usage错误;
全局配置层:读取config gmail_no_send键,若开启同样拦截;
按账户层:检查no-send账户列表(config no-send体系),即使--dry-run提前退出也能在这层被挡住。

关键设计细节:它维护了一个发信命令的"点路径"白名单gmailSendCommandPaths,精确匹配以下 8 条路径——send、gmail.send、gmail.reply、gmail.reply-all、gmail.replyall、gmail.autoreply、gmail.forward、gmail.fwd、gmail.drafts.send。这意味着护栏覆盖的不只是gog gmail send,还包括 reply、reply-all、autoreply、forward 与drafts send等一切会产生外发邮件的命令变体,别名路径(fwd、replyall)也不会漏网。

对应的配置面由gog config命令族管理,可参考 gog-config-no-send.md、gog-config-no-send-set.md、gog-config-no-send-remove.md。

发信路径的参数校验:在 dry-run 之前就不发请求

以gog gmail send为例(完整参数见 docs/commands/gog-gmail-send.md),internal/cmd/gmail_send.go 中GmailSendCmd的字段定义和Run方法的校验逻辑体现了"先本地校验、后 API 调用"的原则:

必填关系:--to必填,除非使用--reply-all;--subject在回复场景可继承(自动加Re:前缀);正文必须提供--body/--body-file/--body-html/--body-html-file之一(-表示 stdin)。
回复约束:--reply-all与--quote都要求同时给出--reply-to-message-id或--thread-id,且二者只能选其一(源码第 91-93 行显式报错)。
追踪约束:--track-split必须搭配--track;--track必须使用 HTML 正文(追踪像素必须位于 HTML 中),否则--track与纯文本互斥。
原始发信:--raw-file走独立的runRaw分支,发送精确的 RFC822 报文,且不允许与 compose 类参数混用。
dry-run 友好:收件人列表在 dry-run 之前就先解析完毕,这样gog gmail send --dry-run可以在不发起任何 API 调用的情况下打印出将要构建的消息(收件人、主题、线程等),恶意或错误输入在本地即失败。

相关测试可参考 internal/cmd/execute_gmail_send_reply_test.go、internal/cmd/gmail_send_raw_test.go。

搜索路径的实现要点

gog gmail search使用标准 Gmail query 语法,源码 internal/cmd/gmail_search.go 中GmailSearchCmd定义了它专属的参数:

--max(别名--limit,默认 10)与--page页码 token;--all翻页取全部结果;
--fail-empty:无结果时以退出码 3 退出,便于 shell 管道判断;
--count:报告整个查询的匹配数(精确值totalMatches或下界totalMatchesAtLeast),搭配--all免费获得,--results-only下不可用;
--from-contact:先解析 Google 联系人,把from:(email OR email)拼入查询——一个联系人多个地址时也能一次命中;
--timezone/--local:控制输出时区(IANA 时区名),默认依次为GOG_TIMEZONE环境变量、配置文件、本地时区。

执行链路为:Users.Threads.List拉取线程 → 必要时用countGmailThreadMatches统计匹配数 →fetchLabelIDToName将标签 ID 翻译为标签名 →fetchThreadDetails逐线程取详情后渲染。JSON 输出形如{ "threads": [...], "nextPageToken": "..." },配合--count还会追加totalMatches字段。README 中给出的最小权限示例正是这条链路:

gog --readonly gmail search 'is:unread newer_than:7d' --max 10 --json

批量与设置类操作的边界说明

gog gmail batch:参考文档的括号注释值得注意——"permanent delete requires broader Gmail scope; use gmail trash for normal trashing",即永久删除需要更广的 Gmail 权限,普通用户应使用trash(走modify权限即可)。
gog gmail trash支持两种形态:直接传<messageId>...,或用-q/--query按 Gmail 查询批量回收,--max默认上限 100 条(见 docs/commands/gog-gmail-trash.md)。
gog gmail settings下管理过滤器、委托、转发地址、自动转发、send-as、假期回复与 watch。其中 watch 子族(见 gog-gmail-settings-watch.md)基于 Gmail 历史 + Pub/Sub 实现收件事件消费,例如 gog-gmail-settings-watch-pull.md 的pull命令带--exclude-labels(默认SPAM,TRASH)与--fetch-delay(默认 3s)等参数;其底层实现分布在 internal/gmailwatch/ 与 internal/cmd/gmail_watch_serve.go 等文件,配套文档为 docs/watch.md。

Agent 安全:把 Gmail 能力"锁死"到只读搜索

gogcli 的 Agent 集成场景(README.md 中的示例)展示了如何把gog gmail的能力面收敛到最小集合:

gog --account work \ --enable-commands-exact gmail.search,gmail.get \ --gmail-no-send --readonly --no-input --wrap-untrusted --json \ gmail search 'newer_than:7d'

这一行同时启用了五道护栏:--enable-commands-exact精确白名单(父命令不会连带放行子命令)、--gmail-no-send拦截一切发信路径、--readonly运行时阻断变更类 API 请求、--no-input禁止交互提示(CI 友好)、--wrap-untrusted将抓取到的文本字段包裹在外部不可信内容标记内,降低提示注入风险。多账户环境下再用--account指定操作对象。

此外,授权面也可从源头收窄:gog auth add you@example.com --services gmail --gmail-scope send只授予发信权限,--gmail-scope read-send则只读+发信,均不包含邮箱修改与设置管理权限。仓库还提供了 safety-profiles/ 目录下的预制安全档案(如 readonly.yaml、agent-safe.yaml)与配套文档 docs/safety-profiles.md,可把上述参数组合固化为可复用的 profile。