gog-cli

gogcli (gog)

gog 是一款快速、便于脚本使用的 Google 服务命令行工具。它以 JSON 为先，支持多个账号和 OAuth 客户端，并为 Agent 和 CI 使用设置了明确的安全防护措施。

权威上游仓库：https://github.com/steipete/gogcli

本技能已根据上游 gog v0.13.0（2026-04-20）更新。需要确认确切语法时，请运行 gog <command> --help 或 gog schema --json；命令接口变化很快，对喜欢过时笔记的人来说实在不太方便。

操作规则

• 检查和编写脚本时，优先使用 gog --json ... | jq ...。
• 只有在稳定的 TSV 比 JSON 更方便时，才使用 --plain。
• 准备变更或用户意图不明确时，对支持的变更操作使用 --dry-run。
• 在自动化中使用 --no-input，以便命令在需要提示时失败，而不是等待输入。
• 仅当用户要求执行破坏性、公开、发送或管理员操作，或你已清楚说明其影响后，才使用 --force。
• 不要擅自修复 OAuth、授权许可、密钥环或 Workspace 委派问题。请向用户展示他们需要运行的确切命令。
• 除非用户明确要求，否则不要导出令牌、打印机密、开放公开共享、添加委派或转发、发送邮件、暂停用户或永久删除数据。
• 对于必须禁止发送邮件的 Agent 运行，请添加 --gmail-no-send、设置 GOG_GMAIL_NO_SEND=1，或运行 gog config no-send set <account> 进行配置。

安装和身份验证

brew install gogcli
gog auth credentials set ~/Downloads/client_secret_....json
gog auth add [email protected] --services gmail,calendar,drive
gog auth list --check

注意：

• Homebrew 现在使用 brew install gogcli；旧的 tap 示例已过时。
• gog auth add 默认使用 --services user。请根据任务需要指定服务。
• --services all 仅作为向后兼容的 user 别名接受；需要使用所有 API 时不要使用它。
• 请使用 --readonly、--drive-scope readonly|file|full 和 --gmail-scope readonly|full，遵循最小权限原则。
• Keep 和 Admin 需要 Workspace 服务账号／全域委派。Google Chat、Groups、目录和 Classroom 也有 Workspace 限制。
• 对于无头环境或 CI，可考虑使用 --manual、--remote、--access-token 或 GOG_AUTH_MODE=adc。

完整身份验证模式请参阅 references/authentication.md。

全局标志

--account, -a <email|alias|auto>   # account selection
--client <name>                    # named OAuth client/token bucket
--access-token <token>             # direct short-lived token; also GOG_ACCESS_TOKEN
--json, -j                         # machine-readable JSON
--plain, -p                        # stable TSV
--results-only                     # JSON primary result only
--select <fields>                  # best-effort JSON projection
--dry-run, -n                      # preview supported writes
--force, -y                        # skip confirmations
--no-input                         # never prompt
--enable-commands <csv>            # allowlist top-level or dotted commands
--disable-commands <csv>           # denylist top-level or dotted commands
--gmail-no-send                    # block Gmail send operations
--verbose, -v                      # debug logging

常用命令别名：

gog send ...             # alias for gog gmail send
gog ls                   # alias for gog drive ls
gog search "budget"      # alias for gog drive search
gog download <fileId>    # alias for gog drive download
gog upload ./file.pdf    # alias for gog drive upload
gog me                   # alias for gog people me
gog status               # alias for gog auth status
gog open <id-or-url>     # best-effort Google web URL, offline

高价值工作流

账号选择

gog auth alias set work [email protected]
gog --account work gmail search 'is:unread newer_than:2d'
GOG_ACCOUNT=work gog calendar events primary --today
gog --client work auth credentials set ~/Downloads/work-client.json
gog --client work auth add [email protected] --services gmail,calendar

Gmail

gog --json gmail search 'is:unread newer_than:7d' | jq -r '.threads[].id'
gog gmail messages search 'from:[email protected] has:attachment' --include-body
gog gmail messages search 'subject:report newer_than:30d' --full
gog gmail thread get <threadId> --download --out-dir ./attachments
gog gmail labels modify <threadId> --add Project --remove INBOX
gog gmail messages modify <messageId> --add STARRED
gog gmail send --to [email protected] --subject "Hello" --body-file ./body.txt
gog gmail forward <messageId> --to [email protected] --note "FYI"

转发、自动回复、监控／Pub/Sub、过滤器、委派、发送身份、标签颜色、批量操作和跟踪功能，请参阅 references/gmail.md。

Calendar

gog calendar calendars
gog calendar events primary --today --weekday
gog calendar events --all --from "2026-04-25T00:00:00+02:00" --to "2026-04-26T00:00:00+02:00"
gog calendar freebusy --cal primary --from "2026-04-25T09:00:00+02:00" --to "2026-04-25T17:00:00+02:00"
gog calendar create primary --summary "Planning" --from "2026-04-25T14:00:00+02:00" --to "2026-04-25T14:30:00+02:00" --attendees "[email protected],[email protected]" --with-meet
gog calendar respond primary <eventId> --status accepted --send-updates all

生成日期时间时，请使用带时区偏移的 RFC3339 格式。别名、订阅、辅助日历、扩展属性、专注时间、OOO、工作地点、团队日历和冲突检测，请参阅 references/calendar.md。

Drive、Docs、Sheets、Slides、Forms、Apps Script

gog drive search "invoice filetype:pdf" --max 20
gog drive upload ./report.md --convert-to doc --parent <folderId>
gog drive upload ./deck.pdf --replace <fileId> --name "Board Deck.pdf"
gog drive share <fileId> --to user --email [email protected] --role commenter
gog docs write <docId> --file ./brief.md --replace --markdown
gog docs sed <docId> 's/status/{b c=green}approved/g' --dry-run
gog sheets update <spreadsheetId> 'Sheet1!A1' '[["Name","Score"],["Ada",98]]'
gog sheets chart list <spreadsheetId>
gog slides thumbnail <presentationId> <slideId> --out ./slide.png
gog forms responses list <formId> --max 20
gog appscript run <scriptId> myFunction --params '["arg1", 123]'

当前的文件／内容命令请参阅 references/drive-docs.md。Docs sed 格式设置请参阅 references/sedmat.md。

其他服务

gog contacts search "Ada"
gog tasks lists
gog tasks add <tasklistId> --title "Weekly review" --due "2026-04-27" --repeat weekly
gog chat messages send spaces/<spaceId> --text "Build complete"
gog groups members [email protected]
gog admin users list --domain example.com
gog keep search "receipt"

Chat、Classroom、Contacts、Tasks、People、Groups、Admin、Keep 和时间工具请参阅 references/other-services.md。

脚本编写模式

# Inspect shape first
gog --json gmail search 'is:unread' --max 3 | jq .

# Use pagination/all-pages where available
gog --json calendar events primary --from today --to tomorrow --all-pages

# Fail cleanly when a supported list command has no results
gog --json calendar events primary --query "unlikely query" --fail-empty

# Batch with xargs after checking output
gog --json gmail search 'older_than:1y label:newsletter' --max 200 | \
  jq -r '.threads[].id' | \
  xargs -n 50 gog gmail labels modify --remove INBOX

# Agent-safe command surface
GOG_ENABLE_COMMANDS=calendar.events,calendar.freebusy,tasks \
  gog --no-input --json calendar events primary --today

参考资料索引

• references/command-reference.md - 根据 gog schema --json 生成的命令索引
• references/authentication.md - OAuth 客户端、服务账号、作用域、密钥环、无头身份验证
• references/configuration.md - 配置键、环境变量、输出模式、安全开关
• references/gmail.md - Gmail 搜索、读取、发送、标签、设置、监控、跟踪、自动回复
• references/calendar.md - Calendar 列表、事件写入、日程安排、特殊事件、别名
• references/drive-docs.md - Drive、Docs、Sheets、Slides、Forms、Apps Script
• references/sedmat.md - Docs sed／格式设置 DSL
• references/other-services.md - Chat、Classroom、Contacts、Tasks、People、Groups、Admin、Keep