gog

用途

gog 是一个 Google Workspace 命令行工具（CLI），用于在终端中访问和操作 Gmail、Google 日历（Calendar）、Google Drive、通讯录（Contacts）、Google 表格（Sheets）和 Google 文档（Docs）。它适合需要以脚本或命令方式处理这些服务的场景。

主要能力

Gmail：搜索邮件与邮件消息、发送纯文本/多行/标准输入/HTML 邮件、创建草稿、发送草稿、回复邮件。
Calendar：列出日历事件、创建事件（含设置事件颜色）、更新事件、查看可用颜色。
Drive：搜索文件。
Contacts：列出通讯录。
Sheets：读取单元格、更新单元格、追加行、清除内容、获取表格元数据。
Docs：导出文档、查看文档内容（cat）、复制（copy）。

使用方式

一次性配置（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

配置完成后即可使用下列命令。可设置 GOG_ACCOUNT=you@gmail.com 以避免重复输入 --account。用于脚本时建议使用 --json 配合 --no-input。

常用命令

Gmail 线程搜索：

gog gmail search 'newer_than:7d' --max 10

Gmail 逐封邮件搜索（忽略会话线程）：

gog gmail messages search "in:inbox from:ryanair.com" --max 20 --account you@example.com

Gmail 发送（纯文本）：

gog gmail send --to a@b.com --subject "Hi" --body "Hello"

Gmail 发送（多行）：

gog gmail send --to a@b.com --subject "Hi" --body-file ./message.txt

Gmail 发送（标准输入）：

gog gmail send --to a@b.com --subject "Hi" --body-file -

Gmail 发送（HTML）：

gog gmail send --to a@b.com --subject "Hi" --body-html "<p>Hello</p>"

Gmail 创建草稿：

gog gmail drafts create --to a@b.com --subject "Hi" --body-file ./message.txt

Gmail 发送草稿：

gog gmail drafts send <draftId>

Gmail 回复：

gog gmail send --to a@b.com --subject "Re: Hi" --body "Reply" --reply-to-message-id <msgId>

Calendar 列出事件：

gog calendar events <calendarId> --from <iso> --to <iso>

Calendar 创建事件：

gog calendar create <calendarId> --summary "Title" --from <iso> --to <iso>

Calendar 创建带颜色事件：

gog calendar create <calendarId> --summary "Title" --from <iso> --to <iso> --event-color 7

Calendar 更新事件：

gog calendar update <calendarId> <eventId> --summary "New Title" --event-color 4

Calendar 查看颜色：

gog calendar colors

Drive 搜索：

gog drive search "query" --max 10

Contacts 列表：

gog contacts list --max 20

Sheets 读取：

gog sheets get <sheetId> "Tab!A1:D10" --json

Sheets 更新：

gog sheets update <sheetId> "Tab!A1:B2" --values-json '[["A","B"],["1","2"]]' --input USER_ENTERED

Sheets 追加：

gog sheets append <sheetId> "Tab!A:C" --values-json '[["x","y","z"]]' --insert INSERT_ROWS

Sheets 清除：

gog sheets clear <sheetId> "Tab!A2:Z"

Sheets 元数据：

gog sheets metadata <sheetId> --json

Docs 导出：

gog docs export <docId> --format txt --out /tmp/doc.txt

Docs 查看：

gog docs cat <docId>

日历颜色

使用 gog calendar colors 查看所有可用事件颜色（ID 1–11），并通过 --event-color <id> 标志为事件添加颜色。事件颜色 ID（来自 gog calendar colors 输出）：

1: #a4bdfc 2: #7ae7bf 3: #dbadff 4: #ff887c 5: #fbd75b 6: #ffb878 7: #46d6db 8: #e1e1e1 9: #5484ed 10: #51b749 11: #dc2127

邮件格式

优先使用纯文本。多段消息使用 --body-file（或 --body-file - 从标准输入读取）。
--body-file 同样适用于草稿和回复。
--body 不会转义 \n。如果需要内联换行，使用 heredoc 或 $'Line 1\n\nLine 2'。
仅在需要富文本格式时使用 --body-html。
HTML 标签：<p> 表示段落，<br> 表示换行，<strong> 表示加粗，<em> 表示斜体，<a href="url"> 表示链接，<ul>/<li> 表示列表。

示例（通过标准输入发送纯文本）：

gog gmail send --to recipient@example.com \
  --subject "Meeting Follow-up" \
  --body-file - <<'EOF'
Hi Name,

Thanks for meeting today. Next steps:
- Item one
- Item two

Best regards,
Your Name
EOF

示例（HTML 列表）：

gog gmail send --to recipient@example.com \
  --subject "Meeting Follow-up" \
  --body-html "<p>Hi Name,</p><p>Thanks for meeting today. Here are the next steps:</p><ul><li>Item one</li><li>Item two</li></ul><p>Best regards,<br>Your Name</p>"

适用场景

在终端中快速搜索、发送和管理 Gmail 邮件与会话线程。
以命令行方式批量查询、创建和更新 Google 日历事件。
搜索 Drive 文件、列出通讯录联系人。
读取、更新、追加、清除 Google 表格数据。
导出或查看 Google 文档内容。
用于脚本或自动化流程，配合 --json 与 --no-input 使用。

限制与注意事项

需要先完成 OAuth 配置（gog auth credentials 与 gog auth add）。
可设置 GOG_ACCOUNT=you@gmail.com 以避免重复输入 --account。
脚本化场景建议使用 --json 配合 --no-input。
Sheets 值可通过 --values-json（推荐）或内联行传递。
Docs 支持 export/cat/copy；原地编辑需要 Docs API 客户端（不在 gog 中）。
发送邮件或创建事件前应确认。
gog gmail search 每行返回一个会话线程；需要返回每封独立邮件时使用 gog gmail messages search。