用途：gog 是 Google Workspace 的命令行工具，覆盖 Gmail、Calendar、Drive、Contacts、Sheets 与 Docs。使用前需完成 OAuth 设置；优先使用已授权的主机账号，先执行目标命令，仅在出现认证错误后再进入设置，且不要在对话中提供密码、客户端密钥或刷新令牌。
设置（一次性）：
gog auth credentials /path/to/client_secret.json
gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets
gog auth list
远程/无头主机：优先在网关上使用实时回调监听，通过 ssh -L <port>:127.0.0.1:<port> user@gateway-host 转发端口后打开授权 URL。无监听时由操作员在可信 shell 中选择粘贴模式（--manual，或 --remote --step 1 打印 auth_url 后执行 --remote --step 2 --auth-url <callback-url>）；回调 URL 不得进入聊天或工具输入。远程步骤需保持同一配置上下文：GOG_CONFIG_DIR 优先于 --home，后者优先于 GOG_HOME，并保留 --client、服务/作用域、重定向 URI 和授权选项。若桌面 keyring 不可用，可配置 gog auth keyring file 并设置 GOG_KEYRING_PASSWORD。诊断时查看 gog auth list --check 每条记录与 gog auth doctor 的状态，而非仅看退出码。
常用命令：
gog gmail search 'newer_than:7d' --max 10
gog gmail messages search "in:inbox from:ryanair.com" --max 20 --account you@example.com
gog gmail send --to a@b.com --subject "Hi" --body "Hello"
gog gmail send --to a@b.com --subject "Hi" --body-file ./message.txt
gog gmail drafts create --to a@b.com --subject "Hi" --body-file ./message.txt
gog calendar events <calendarId> --from <iso> --to <iso>
gog calendar create <calendarId> --summary "Title" --from <iso> --to <iso> --event-color 7
gog drive search "query" --max 10
gog contacts list --max 20
gog sheets get <sheetId> "Tab!A1:D10" --json
gog docs export <docId> --format txt --out /tmp/doc.txt
gog docs cat <docId>
邮件格式：优先纯文本，多段内容用 --body-file（- 表示 stdin）；--body 不解析 \n；仅在需要富文本时用 --body-html。可用 gog calendar colors 查看事件颜色 ID 1-11，并以 --event-color <id> 指定。
说明：设置 GOG_ACCOUNT 可省去重复 --account；脚本中建议使用 --json 与 --no-input。Docs 支持 export/cat/copy，原地编辑需要 Docs API 客户端，gog 不提供。gog gmail search 按线程返回一行，需逐封邮件时用 gog gmail messages search。
限制：需自行完成 OAuth 授权与网络策略配置；不提供密码或密钥托管；代理环境下令牌交换或身份查询可能失败。