gogcli

gogcli — 在终端中使用 Google Workspace

gog 是一款快速、以 JSON 为先的命令行工具，支持完整的 Google Workspace 套件。解析结果时，始终使用 --json 获取结构化输出。

环境

export [email protected]
export GOG_KEYRING_PASSWORD=$(secrets lease gog_keyring_password )

每次运行 gog 命令都必须设置这两个变量。使用前，请从 agent-secrets 获取密钥环密码。

快速参考

Gmail

# Search (default: threads)
gog gmail search 'newer_than:1d' --max 10 --json
gog gmail search 'is:unread' --max 20 --json
gog gmail search 'from:[email protected] newer_than:7d' --max 10 --json

# Message-level search with bodies
gog gmail messages search 'is:unread' --max 5 --include-body --json

# Read thread
gog gmail thread get <threadId> --json

# Send
gog gmail send --to [email protected] --subject "Subject" --body "Body text"
gog gmail send --to [email protected] --subject "Hi" --body-html "<p>Hello</p>"

# Labels
gog gmail labels list --json
gog gmail thread modify <threadId> --add STARRED --remove INBOX

Calendar

# Today / this week
gog calendar events primary --today --json
gog calendar events primary --week --json
gog calendar events primary --tomorrow --json
gog calendar events primary --days 7 --json

# All calendars
gog calendar events --all --today --json

# Search
gog calendar search "meeting" --today --json

# Create event
gog calendar create primary \
  --summary "Meeting" \
  --from 2025-01-15T10:00:00Z \
  --to 2025-01-15T11:00:00Z \
  --attendees "[email protected]"

# Check availability
gog calendar freebusy --calendars "primary" \
  --from 2025-01-15T00:00:00Z --to 2025-01-16T00:00:00Z --json

# List calendars
gog calendar calendars --json

Drive

gog drive ls --max 20 --json
gog drive search "invoice" --max 20 --json
gog drive upload ./file.pdf --parent <folderId>
gog drive download <fileId> --out ./file.pdf
gog drive mkdir "New Folder"

Tasks

gog tasks lists --json
gog tasks list <tasklistId> --max 50 --json
gog tasks add <tasklistId> --title "New task"
gog tasks done <tasklistId> <taskId>

Contacts

gog contacts search "Name" --max 10 --json
gog contacts list --max 50 --json

Sheets

gog sheets metadata <spreadsheetId> --json
gog sheets get <spreadsheetId> 'Sheet1!A1:B10' --json
gog sheets update <spreadsheetId> 'A1' 'val1|val2,val3|val4'
gog sheets append <spreadsheetId> 'Sheet1!A:C' 'new|row|data'

Docs / Slides

gog docs cat <docId>                           # Read doc as text
gog docs export <docId> --format pdf --out doc.pdf
gog slides export <presentationId> --format pdf --out deck.pdf

Chat（仅限 Workspace）

gog chat spaces list --json
gog chat messages list spaces/<spaceId> --max 10 --json
gog chat dm send [email protected] --text "message"

输出模式

标志	用途
--json	将结构化 JSON 输出到 stdout（解析时始终优先使用）
--plain	稳定的 TSV（使用制表符，不带颜色）
（无）	人类可读的表格

错误和进度信息会输出到 stderr。可将 --json 输出通过管道传给 jq 进行筛选。

常用模式

批量搜索 Gmail 并生成摘要

gog gmail messages search 'is:unread newer_than:1d' --max 20 --include-body --json | jq '.messages[] | {from, subject, body}'

查找下一个空闲时段

gog calendar freebusy --calendars "primary" --from today --to tomorrow --json

今日议程

gog calendar events primary --today --json | jq '.events[] | {summary, start: .start.dateTime, end: .end.dateTime}'

身份验证设置（一次性）

如果 gog 返回身份验证错误：

export GOG_KEYRING_PASSWORD=$(secrets lease gog_keyring_password )
gog auth add [email protected] --services user
# Complete OAuth in browser, then verify:
gog auth list --check

故障排除

• “未找到密钥”：未设置密钥环密码。请导出 GOG_KEYRING_PASSWORD。
• “没有 gmail 身份验证”：需要运行 gog auth add <email> --services gmail（或使用 user 为所有服务添加身份验证）。
• 403 权限范围不足：使用 --force-consent 重新进行身份验证，以添加缺失的权限范围。
• 钥匙串已锁定：此系统使用 file 后端。请设置 GOG_KEYRING_PASSWORD 环境变量。