steipete/gogcli

# 🧭 gogcli — 终端里的 Google。  快速、对脚本友好的 CLI，支持 Gmail、Calendar、Chat、Classroom、Drive、Docs、Slides、Sheets、Forms、Apps Script、Contacts、Tasks、People、Groups (Workspace) 和 Keep (仅限 Workspace)。内置 JSON 优先输出、多账户支持以及最小权限认证。 ## 功能特性 - **Gmail** - 搜索会话和邮件、发送邮件、查看附件、管理标签/草稿/过滤器/委派/休假设置、历史记录和 watch (Pub/Sub push) - **邮件追踪** - 使用 `gog gmail send --track` 追踪邮件打开情况，带有一个轻量的 Cloudflare Worker 后端 - **Calendar** - 列出/创建/更新活动、检测冲突、管理邀请、查看忙碌状态、团队日历、提议新时间、专注/OOO/工作地点活动、循环 + 提醒 - **Classroom** - 管理课程、名单、作业/资料、提交、公告、主题、邀请、监护人、个人资料 - **Chat** - 列出/查找/创建空间、列出消息/会话（按会话/未读过滤）、发送消息和 DM（仅限 Workspace） - **Drive** - 列出/搜索/上传/下载文件、管理权限/评论、组织文件夹、列出共享云端硬盘 - **Contacts** - 搜索/创建/更新联系人、访问 Workspace 目录/其他联系人 - **Tasks** - 管理任务列表和任务：获取/创建/添加/更新/完成/撤销/删除/清除、重复计划 - **Sheets** - 读取/写入/更新电子表格、插入行/列、格式化单元格、读取备注、创建新工作表（并通过 Drive 导出） - **Forms** - 创建/获取表单并查看回复 - **Apps Script** - 创建/获取项目、查看内容并运行函数 - **Docs/Slides** - 通过 Drive 导出为 PDF/DOCX/PPTX（以及创建/复制、docs-to-text 和带 Markdown 格式、图片和表格的 **sedmat** sed 风格文档编辑） - **People** - 访问个人资料信息 - **Keep (仅限 Workspace)** - 列出/获取/搜索笔记并下载附件（服务账号 + 域范围委派） - **Groups** - 列出您所属的群组、查看群组成员 (Google Workspace) - **本地时间** - 为脚本和代理快速显示本地/UTC 时间 - **多账户** - 同时管理多个 Google 账户（带别名） - **命令白名单** - 限制顶级命令用于沙箱/代理运行 - **安全凭证存储** - 使用 OS 密钥环或加密的磁盘密钥环（可配置） - **自动刷新 Token** - 认证一次，永久使用 - **最小权限认证** - `--readonly` 和 `--drive-scope` 请求更少的 Scope - **Workspace 服务账号** - 域范围委派认证（配置后优先使用） - **可解析输出** - 用于脚本和自动化的 JSON 模式（Calendar 增加星期几字段） ## 安装说明 ### Homebrew ``` brew install steipete/tap/gogcli ``` ### Arch User Repository ``` yay -S gogcli ``` ### 从源码构建 ``` git clone https://github.com/steipete/gogcli.git cd gogcli make ``` 运行： ``` ./bin/gog --help ``` 帮助： - `gog --help` 显示顶级命令组。 - 使用 `gog --help`（以及更深的子命令）深入了解。 - 查看完整展开的命令列表：`GOG_HELP=full gog --help`。 - 创建快捷方式：`make gog -- --help`（或 `make gog -- gmail --help`）。 - `make gog-help` 显示 CLI 帮助（注意：`make gog --help` 是 Make 自己的帮助；请使用 `--`）。 - 版本：`gog --version` 或 `gog version`。 ## 快速开始 ### 1. 获取 OAuth2 凭证 在添加账户之前，请从 Google Cloud Console 创建 OAuth2 凭证： 1. 打开 Google Cloud Console 凭证页面：https://console.cloud.google.com/apis/credentials 2. 创建项目：https://console.cloud.google.com/projectcreate 3. 启用您需要的 API： - Gmail API: https://console.cloud.google.com/apis/api/gmail.googleapis.com - Google Calendar API: https://console.cloud.google.com/apis/api/calendar-json.googleapis.com - Google Chat API: https://console.cloud.google.com/apis/api/chat.googleapis.com - Google Drive API: https://console.cloud.google.com/apis/api/drive.googleapis.com - Google Classroom API: https://console.cloud.google.com/apis/api/classroom.googleapis.com - People API (Contacts): https://console.cloud.google.com/apis/api/people.googleapis.com - Google Tasks API: https://console.cloud.google.com/apis/api/tasks.googleapis.com - Google Sheets API: https://console.cloud.google.com/apis/api/sheets.googleapis.com - Google Forms API: https://console.cloud.google.com/apis/api/forms.googleapis.com - Apps Script API: https://console.cloud.google.com/apis/api/script.googleapis.com - Cloud Identity API (Groups): https://console.cloud.google.com/apis/api/cloudidentity.googleapis.com 4. 配置 OAuth 同意屏幕：https://console.cloud.google.com/auth/branding 5. 如果您的应用处于“测试中”，请添加测试用户：https://console.cloud.google.com/auth/audience 6. 创建 OAuth 客户端： - 前往 https://console.cloud.google.com/auth/clients - 点击“创建客户端” - 应用类型：“Desktop app” - 下载 JSON 文件（通常名为 `client_secret_....apps.googleusercontent.com.json`） ### 2. 存储凭证 ``` gog auth credentials ~/Downloads/client_secret_....json ``` 对于多个 OAuth 客户端/项目： ``` gog --client work auth credentials ~/Downloads/work-client.json gog auth credentials list ``` ### 3. 授权您的账户 ``` gog auth add you@gmail.com ``` 这将打开一个浏览器窗口进行 OAuth 授权。刷新 Token 将安全地存储在您的系统钥匙串中。 无头 / 远程服务器流程（服务器上没有浏览器）： 手动交互流程（推荐）： ``` gog auth add you@gmail.com --services user --manual ``` - CLI 打印一个认证 URL。在本地浏览器中打开它。 - 批准后，从浏览器地址栏复制完整的环回重定向 URL。 - 出现提示时，将该 URL 粘贴回终端。 分离远程流程（`--remote`，适用于两步/脚本化交接）： ``` # 第 1 步：打印 auth URL（在本地浏览器中打开） gog auth add you@gmail.com --services user --remote --step 1 # 第 2 步：粘贴浏览器地址栏中的完整重定向 URL gog auth add you@gmail.com --services user --remote --step 2 --auth-url 'http://127.0.0.1:/oauth2/callback?code=...&state=...' ``` - `state` 会在磁盘上缓存一小段时间（约 10 分钟）。如果过期，请重新运行第 1 步。 - 远程第 2 步需要一个包含 `state` 的重定向 URL（强制进行 state 检查）。 ### 4. 测试认证 ``` export GOG_ACCOUNT=you@gmail.com gog gmail labels list ``` ## 认证与密钥 ### 账户与 Token `gog` 将您的 OAuth 刷新 Token 存储在“密钥环”后端中。默认值为 `auto`（您的操作系统/环境中可用的最佳后端）。 在运行 `gog auth add` 之前，您必须通过 `gog auth credentials ` 存储一次 OAuth 客户端凭证（从 Cloud Console 下载 Desktop app OAuth 客户端 JSON）。对于多个客户端，使用 `gog --client auth credentials ...`；Token 按客户端隔离。 列出账户： ``` gog auth list ``` 验证 Token 是否可用（有助于发现已撤销/过期的 Token）： ``` gog auth list --check ``` 账户可以通过 OAuth 刷新 Token 或 Workspace 服务账号（域范围委派）进行授权。如果为账户配置了服务账号密钥，它将优先于 OAuth 刷新 Token（参见 `gog auth list`）。 显示当前活动账户的认证状态/服务： ``` gog auth status ``` ### 多个 OAuth 客户端 使用 `--client`（或 `GOG_CLIENT`）选择一个命名的 OAuth 客户端： ``` gog --client work auth credentials ~/Downloads/work.json gog --client work auth add you@company.com ``` 用于自动选择的可选域映射： ``` gog --client work auth credentials ~/Downloads/work.json --domain example.com ``` 工作原理： - 默认客户端为 `default`（存储在 `credentials.json` 中）。 - 命名客户端存储为 `credentials-.json`。 - Token 按客户端隔离（`token::`）；默认值也按客户端设置。 客户端选择顺序（当未设置 `--client` 时）： 1. `--client` / `GOG_CLIENT` 2. `account_clients` 配置 (email -> client) 3. `client_domains` 配置 (domain -> client) 4. 以电子邮件域命名的凭证文件 (`credentials-example.com.json`) 5. `default` 配置示例 (JSON5)： ``` { account_clients: { "you@company.com": "work" }, client_domains: { "example.com": "work" }, } ``` 列出存储的凭证： ``` gog auth credentials list ``` 有关完整的客户端选择和映射规则，请参见 `docs/auth-clients.md`。 ### 密钥环后端：Keychain vs 加密文件 后端： - `auto`（默认）：选择最适合平台的后端。 - `keychain`：macOS Keychain（在 macOS 上推荐；避免密码管理）。 - `file`：加密的磁盘密钥环（需要密码）。 通过命令设置后端（将 `keyring_backend` 写入 `config.json`）： ``` gog auth keyring file gog auth keyring keychain gog auth keyring auto ``` 显示当前后端 + 来源（环境变量/配置/默认值）和配置路径： ``` gog auth keyring ``` 非交互式运行 (CI/ssh)：文件后端需要 `GOG_KEYRING_PASSWORD`。 ``` export GOG_KEYRING_PASSWORD='...' gog --no-input auth status ``` 通过环境变量强制后端（覆盖配置）： ``` export GOG_KEYRING_BACKEND=file ``` 优先级：`GOG_KEYRING_BACKEND` 环境变量覆盖 `config.json`。 ## 配置 ### 账户选择 使用 Flag 或环境变量指定账户： ``` # 通过 flag gog gmail search 'newer_than:7d' --account you@gmail.com # 通过 alias gog auth alias set work work@company.com gog gmail search 'newer_than:7d' --account work # 通过环境变量 export GOG_ACCOUNT=you@gmail.com gog gmail search 'newer_than:7d' # 自动选择（默认账户或单个存储的 token） gog gmail labels list --account auto ``` 列出已配置的账户： ``` gog auth list ``` ### 输出 - 默认：stdout 上人类友好的表格。 - `--plain`：stdout 上稳定的 TSV（保留制表符；最适合管道传输到期望 `\t` 的工具）。 - `--json`：stdout 上的 JSON（最适合脚本编写）。 - 面向人类的提示/进度信息输出到 stderr。 - 颜色仅在富 TTY 输出中启用，对于 `--json` 和 `--plain` 会自动禁用。 ### 服务 Scopes 默认情况下，`gog auth add` 请求访问 **user** 服务（有关当前列表和 Scope，请参见 `gog auth services`）。 请求更少的 Scope： ``` gog auth add you@gmail.com --services drive,calendar ``` 请求只读 Scope（写入操作将因 403 Scope 不足而失败）： ``` gog auth add you@gmail.com --services drive,calendar --readonly ``` 控制 Drive 的 Scope（默认：`full`）： ``` gog auth add you@gmail.com --services drive --drive-scope full gog auth add you@gmail.com --services drive --drive-scope readonly gog auth add you@gmail.com --services drive --drive-scope file ``` 注意： - `--drive-scope readonly` 足以通过 Drive 进行列出/下载/导出（写入操作将返回 403）。 - `--drive-scope file` 具有写入能力（仅限于由此应用创建/打开的文件），并且不能与 `--readonly` 组合使用。 如果您稍后需要添加服务而 Google 没有返回刷新 Token，请使用 `--force-consent` 重新运行： ``` gog auth add you@gmail.com --services user --force-consent # 或者仅添加 Sheets gog auth add you@gmail.com --services sheets --force-consent ``` `--services all` 作为 `user` 的别名被接受，以实现向后兼容。 Docs 命令通过 Drive API 实现，`docs` 请求 Drive 和 Docs API Scope。 服务 Scope 矩阵（自动生成；运行 `go run scripts/gen-auth-services-md.go`）： | Service | User | APIs | Scopes | Notes | | --- | --- | --- | --- | --- | | gmail | yes | Gmail API | `https://www.googleapis.com/auth/gmail.modify`
`https://www.googleapis.com/auth/gmail.settings.basic`
`https://www.googleapis.com/auth/gmail.settings.sharing` | | | calendar | yes | Calendar API | `https://www.googleapis.com/auth/calendar` | | | chat | yes | Chat API | `https://www.googleapis.com/auth/chat.spaces`
`https://www.googleapis.com/auth/chat.messages`
`https://www.googleapis.com/auth/chat.memberships`
`https://www.googleapis.com/auth/chat.users.readstate.readonly` | | | classroom | yes | Classroom API | `https://www.googleapis.com/auth/classroom.courses`
`https://www.googleapis.com/auth/classroom.rosters`
`https://www.googleapis.com/auth/classroom.coursework.students`
`https://www.googleapis.com/auth/classroom.coursework.me`
`https://www.googleapis.com/auth/classroom.courseworkmaterials`
`https://www.googleapis.com/auth/classroom.announcements`
`https://www.googleapis.com/auth/classroom.topics`
`https://www.googleapis.com/auth/classroom.guardianlinks.students`
`https://www.googleapis.com/auth/classroom.profile.emails`
`https://www.googleapis.com/auth/classroom.profile.photos` | | | drive | yes | Drive API | `https://www.googleapis.com/auth/drive` | | | docs | yes | Docs API, Drive API | `https://www.googleapis.com/auth/drive`
`https://www.googleapis.com/auth/documents` | Export/copy/create via | | slides | yes | Slides API, Drive API | `https://www.googleapis.com/auth/drive`
`https://www.googleapis.com/auth/presentations` | Create/edit presentations | | contacts | yes | People API | `https://www.googleapis.com/auth/contacts`
`https://www.googleapis.com/auth/contacts.other.readonly`
`https://www.googleapis.com/auth/directory.readonly` | Contacts + other contacts + directory | | tasks | yes | Tasks API | `https://www.googleapis.com/auth/tasks` | | | sheets | yes | Sheets API, Drive API | `https://www.googleapis.com/auth/drive`
`https://www.googleapis.com/auth/spreadsheets` | Export via Drive | | people | yes | People API | `profile` | OIDC profile scope | | forms | yes | Forms API | `https://www.googleapis.com/auth/forms.body`
`https://www.googleapis.com/auth/forms.responses.readonly` | | | appscript | yes | Apps Script API | `https://www.googleapis.com/auth/script.projects`
`https://www.googleapis.com/auth/script.deployments`
`https://www.googleapis.com/auth/script.processes` | | | groups | no | Cloud Identity API | `https://www.googleapis.com/auth/cloud-identity.groups.readonly` | Workspace only | | keep | no | Keep API | `https://www.googleapis.com/auth/keep.readonly` | Workspace only; service account (domain-wide delegation) | ### 服务账号（仅限 Workspace） 服务账号是归属于 Google Cloud 项目的非人类 Google 身份。在 Google Workspace 中，服务账号可以通过**域范围委派**（由管理员控制）模拟用户，并以该用户身份访问 Gmail/Calendar/Drive 等 API。 在 `gog` 中，服务账号是一种**可选的认证方式**，可以按账户电子邮件进行配置。如果为账户配置了服务账号密钥，它将优先于 OAuth 刷新 Token（参见 `gog auth list`）。 #### 1) 创建服务账号 (Google Cloud) 1. 创建（或选择）一个 Google Cloud 项目。 2. 启用您将使用的 API（例如 Gmail、Calendar、Drive、Sheets、Docs、People、Tasks、Cloud Identity）。 3. 前往 **IAM & Admin → Service Accounts** 并创建一个服务账号。 4. 在服务账号详情中，启用 **Domain-wide delegation**。 5. 创建密钥（**Keys → Add key → Create new key → JSON**）并下载 JSON 密钥文件。 #### 2) 白名单 Scopes (Google Workspace 管理控制台) 域范围委派由 Workspace 管理员设置强制执行。 1. 打开 **Admin console → Security → API controls → Domain-wide delegation**。 2. 添加新的 API 客户端： - Client ID：使用来自 Google Cloud 的服务账号的“Client ID”。 - OAuth scopes：您要允许的逗号分隔的 Scope 列表（从 `gog auth services` 和/或您的 `gog auth add --services ...` 使用情况中复制）。 如果白名单中缺少某个 Scope，服务账号 Token 生成可能会失败（或 API 调用将因权限不足返回 403）。 #### 3) 配置 `gog` 使用服务账号 为您要模拟的用户存储密钥： ``` gog auth service-account set you@yourdomain.com --key ~/Downloads/service-account.json ``` 验证 `gog` 是否对该账户优先使用服务账号： ``` gog --account you@yourdomain.com auth status gog auth list ``` ### Google Keep（仅限 Workspace） Keep 需要 Workspace + 域范围委派。您可以通过上面的通用服务账号命令进行配置（推荐），或使用旧的 Keep 辅助程序： ``` gog auth service-account set you@yourdomain.com --key ~/Downloads/service-account.json gog keep list --account you@yourdomain.com gog keep get --account you@yourdomain.com ``` ### 环境变量 - `GOG_ACCOUNT` - 要使用的默认账户电子邮件或别名（避免重复 `--account`；否则使用密钥环默认值或单个存储的 Token） - `GOG_CLIENT` - OAuth 客户端名称（选择存储的凭证 + Token 桶） - `GOG_JSON` - 默认 JSON 输出 - `GOG_PLAIN` - 默认纯文本输出 - `GOG_COLOR` - 颜色模式：`auto`（默认）、`always` 或 `never` - `GOG_TIMEZONE` - Calendar/Gmail 的默认输出时区（IANA 名称、`UTC` 或 `local`） - `GOG_ENABLE_COMMANDS` - 顶级命令的逗号分隔白名单（例如 `calendar,tasks`） ### 配置文件 (JSON5) 在 `gog --help` 或 `gog auth keyring` 中查找实际配置路径。 典型路径： - macOS: `~/Library/Application Support/gogcli/config.json` - Linux: `~/.config/gogcli/config.json` (或 `$XDG_CONFIG_HOME/gogcli/config.json`) - Windows: `%AppData%\\gogcli\\config.json` 示例（JSON5 支持注释和尾随逗号）： ``` { // Avoid macOS Keychain prompts keyring_backend: "file", // Default output timezone for Calendar/Gmail (IANA, UTC, or local) default_timezone: "UTC", // Optional account aliases account_aliases: { work: "work@company.com", personal: "me@gmail.com", }, // Optional per-account OAuth client selection account_clients: { "work@company.com": "work", }, // Optional domain -> client mapping client_domains: { "example.com": "work", }, } ``` ### 配置命令 ``` gog config path gog config list gog config keys gog config get default_timezone gog config set default_timezone UTC gog config unset default_timezone ``` ### 账户别名 ``` gog auth alias set work work@company.com gog auth alias list gog auth alias unset work ``` 别名适用于您传递 `--account` 或 `GOG_ACCOUNT` 的任何地方（保留字：`auto`、`default`）。 ### 命令白名单（沙箱） ``` # 仅允许代理使用 calendar + tasks 命令 gog --enable-commands calendar,tasks calendar events --today # 通过环境变量设置相同 export GOG_ENABLE_COMMANDS=calendar,tasks gog tasks list ``` ## 安全 ### 凭证存储 OAuth 凭证安全地存储在您系统的钥匙串中： - **macOS**: Keychain Access - **Linux**: Secret Service (GNOME Keyring, KWallet) - **Windows**: Credential Manager CLI 使用 [github.com/99designs/keyring](https://github.com/99designs/keyring) 进行安全存储。 如果没有可用的 OS 密钥环后端（例如 Linux/WSL/容器），密钥环可以回退到加密的磁盘存储并可能提示输入密码；对于非交互式运行，请设置 `GOG_KEYRING_PASSWORD`。 ### Keychain 提示 (macOS) 当“应用身份”不断变化（不同的二进制路径、`go run` 临时构建、重建到新的 `./bin/gog`、多个副本）时，macOS Keychain 可能会比您预期的更频繁地提示。Keychain 将这些视为不同的应用，因此它会再次询问。 选项： - **默认（推荐）：** 继续使用 Keychain（安全）并运行稳定的 `gog` 二进制路径以减少重复提示。 - **强制 Keychain：** `GOG_KEYRING_BACKEND=keychain`（禁用任何文件后端回退）。 - **完全避免 Keychain 提示：** `GOG_KEYRING_BACKEND=file`（在您的配置目录下将加密条目存储在磁盘上）。 - 同时避免密码提示（CI/非交互式）：设置 `GOG_KEYRING_PASSWORD=...`（权衡：环境变量中的秘密）。 ### 最佳实践 - **永远不要将 OAuth 客户端凭证提交**到版本控制中 - 将客户端凭证存储在项目目录之外 - 为开发和生产使用不同的 OAuth 客户端 - 如果怀疑 Token 泄露，请使用 `--force-consent` 重新授权 - 使用 `gog auth remove ` 删除未使用的账户 ### 开源中的 OAuth Client ID 一些开源 Google CLI 附带从其他桌面应用复制的预配置 OAuth Client ID/Secret，以避免 OAuth 同意验证、测试用户限制或配额问题。这会使同意屏幕/安全电子邮件显示其他应用的名称，并且可能随时停止工作。 `gogcli` 不这样做。支持的认证： - 您自己的 OAuth Desktop 客户端 JSON，通过 `gog auth credentials ...` + `gog auth add ...` - 具有域范围委派的 Google Workspace 服务账号（仅限 Workspace） ## 命令 Flag 别名： - `--out` 也接受 `--output`。 - `--out-dir` 也接受 `--output-dir`（Gmail 会话附件下载）。 ### 认证 ``` gog auth credentials # Store OAuth client credentials gog auth credentials list # List stored OAuth client credentials gog --client work auth credentials # Store named OAuth client credentials gog auth add # Authorize and store refresh token gog auth service-account set --key # Configure service account impersonation (Workspace only) gog auth service-account status # Show service account status gog auth service-account unset # Remove service account gog auth keep --key # Legacy alias (Keep) gog auth keyring [backend] # Show/set keyring backend (auto|keychain|file) gog auth status # Show current auth state/services gog auth services # List available services and OAuth scopes gog auth list # List stored accounts gog auth list --check # Validate stored refresh tokens gog auth remove # Remove a stored refresh token gog auth manage # Open accounts manager in browser gog auth tokens # Manage stored refresh tokens ``` ### Keep（仅限 Workspace） ``` gog keep list --account you@yourdomain.com gog keep get --account you@yourdomain.com gog keep search --account you@yourdomain.com gog keep attachment --account you@yourdomain.com --out ./attachment.bin ``` ### Gmail ``` # 搜索和阅读 gog gmail search 'newer_than:7d' --max 10 gog gmail thread get gog gmail thread get --download # Download attachments to current dir gog gmail thread get --download --out-dir ./attachments gog gmail get gog gmail get --format metadata gog gmail attachment gog gmail attachment --out ./attachment.bin gog gmail url # Print Gmail web URL gog gmail thread modify --add STARRED --remove INBOX # 发送和撰写 gog gmail send --to a@b.com --subject "Hi" --body "Plain fallback" gog gmail send --to a@b.com --subject "Hi" --body-file ./message.txt gog gmail send --to a@b.com --subject "Hi" --body-file - # Read body from stdin gog gmail send --to a@b.com --subject "Hi" --body "Plain fallback" --body-html "

Hello

" # 回复 + 包含引用的原始消息（除非您传递 --body-html，否则自动生成 HTML 引用） gog gmail send --reply-to-message-id --quote --to a@b.com --subject "Re: Hi" --body "My reply" gog gmail drafts list gog gmail drafts create --subject "Draft" --body "Body" gog gmail drafts create --to a@b.com --subject "Draft" --body "Body" gog gmail drafts update --subject "Draft" --body "Body" gog gmail drafts update --to a@b.com --subject "Draft" --body "Body" gog gmail drafts send # 标签 gog gmail labels list gog gmail labels get INBOX --json # Includes message counts gog gmail labels create "My Label" gog gmail labels modify --add STARRED --remove INBOX gog gmail labels delete # Deletes user label (guards system labels; confirm) # 批量操作 gog gmail batch delete gog gmail batch modify --add STARRED --remove INBOX # 过滤器 gog gmail filters list gog gmail filters create --from 'noreply@example.com' --add-label 'Notifications' gog gmail filters delete # 设置 gog gmail autoforward get gog gmail autoforward enable --email forward@example.com gog gmail autoforward disable gog gmail forwarding list gog gmail forwarding add --email forward@example.com gog gmail sendas list gog gmail sendas create --email alias@example.com gog gmail vacation get gog gmail vacation enable --subject "Out of office" --message "..." gog gmail vacation disable # 委派（G Suite/Workspace） gog gmail delegates list gog gmail delegates add --email delegate@example.com gog gmail delegates remove --email delegate@example.com # 监控（Pub/Sub push） gog gmail watch start --topic projects/

/topics/ --label INBOX gog gmail watch serve --bind 127.0.0.1 --token --hook-url http://127.0.0.1:18789/hooks/agent gog gmail watch serve --bind 0.0.0.0 --verify-oidc --oidc-email --hook-url gog gmail watch serve --bind 127.0.0.1 --token --exclude-labels SPAM,TRASH --hook-url http://127.0.0.1:18789/hooks/agent gog gmail history --since ``` Gmail watch (Pub/Sub push)： - 创建 Pub/Sub 主题 + 推送订阅（首选 OIDC；共享 Token 可用于开发）。 - 完整流程 + 载荷详情：`docs/watch.md`。 - `watch serve --exclude-labels` 默认为 `SPAM,TRASH`；ID 区分大小写。 ### 邮件追踪 追踪收件人何时打开您的电子邮件： ``` # 设置本地跟踪配置（按账户；生成密钥；按照打印的部署步骤操作） gog gmail track setup --worker-url https://gog-email-tracker..workers.dev # 发送跟踪 gog gmail send --to recipient@example.com --subject "Hello" --body-html "

Hi!

" --track # 检查打开情况 gog gmail track opens gog gmail track opens --to recipient@example.com # 查看状态 gog gmail track status ``` 文档：`docs/email-tracking.md`（设置/部署）+ `docs/email-tracking-worker.md`（内部原理）。 **注意：** `--track` 需要恰好 1 个收件人（无 cc/bcc）和 HTML 正文（`--body-html` 或 `--quote`）。使用 `--track-split` 发送带有单独追踪 ID 的按收件人消息。追踪 Worker 默认存储 IP/User-Agent + 粗略地理位置。 ### Calendar ``` # 日历 gog calendar calendars gog calendar acl # List access control rules gog calendar colors # List available event/calendar colors gog calendar time --timezone America/New_York gog calendar users # List workspace users (use email as calendar ID) # 事件（带有时区感知的时间 flags） gog calendar events --today # Today's events gog calendar events --tomorrow # Tomorrow's events gog calendar events --week # This week (Mon-Sun by default; use --week-start) gog calendar events --days 3 # Next 3 days gog calendar events --from today --to friday # Relative dates gog calendar events --from today --to friday --weekday # Include weekday columns gog calendar events --from 2025-01-01T00:00:00Z --to 2025-01-08T00:00:00Z gog calendar events --all # Fetch events from all calendars gog calendar events --calendars 1,3 # Fetch events from calendar indices (see gog calendar calendars) gog calendar events --cal Work --cal Personal # Fetch events from calendars by name/ID gog calendar event gog calendar get # Alias for event gog calendar search "meeting" --today gog calendar search "meeting" --tomorrow gog calendar search "meeting" --days 365 gog calendar search "meeting" --from 2025-01-01T00:00:00Z --to 2025-01-31T00:00:00Z --max 50 # 除非您设置 --from/--to/--today/--week/--days，否则搜索默认为 30 天前至 90 天后。 # 提示：设置 GOG_CALENDAR_WEEKDAY=1 以默认输出 calendar 事件的 --weekday。 # JSON 事件输出包含时区和本地化时间（对 agents 很有用）。 gog calendar get --json # { # "event": { # "id": "...", # "summary": "...", # "startDayOfWeek": "Friday", # "endDayOfWeek": "Friday", # "timezone": "America/Los_Angeles", # "eventTimezone": "America/New_York", # "startLocal": "2026-01-23T20:45:00-08:00", # "endLocal": "2026-01-23T22:45:00-08:00", # "start": { "dateTime": "2026-01-23T23:45:00-05:00" }, # "end": { "dateTime": "2026-01-24T01:45:00-05:00" } # } # } # 团队日历（Google Workspace 需要 Cloud Identity API） gog calendar team --today # Show team's events for today gog calendar team --week # Show team's events for the week (use --week-start) gog calendar team --freebusy # Show only busy/free blocks (faster) gog calendar team --query "standup" # Filter by event title # 创建和更新 gog calendar create \ --summary "Meeting" \ --from 2025-01-15T10:00:00Z \ --to 2025-01-15T11:00:00Z gog calendar create \ --summary "Team Sync" \ --from 2025-01-15T14:00:00Z \ --to 2025-01-15T15:00:00Z \ --attendees "alice@example.com,bob@example.com" \ --location "Zoom" gog calendar update \ --summary "Updated Meeting" \ --from 2025-01-15T11:00:00Z \ --to 2025-01-15T12:00:00Z # 创建/更新时发送通知 gog calendar create \ --summary "Team Sync" \ --from 2025-01-15T14:00:00Z \ --to 2025-01-15T15:00:00Z \ --send-updates all gog calendar update \ --send-updates externalOnly # 默认：除非您传递 --send-updates，否则不发送与会者通知。 gog calendar delete \ --send-updates all --force # 重复 + 提醒 gog calendar create \ --summary "Payment" \ --from 2025-02-11T09:00:00-03:00 \ --to 2025-02-11T09:15:00-03:00 \ --rrule "RRULE:FREQ=MONTHLY;BYMONTHDAY=11" \ --reminder "email:3d" \ --reminder "popup:30m" # 通过 --event-type 设置特殊事件类型（focus-time/out-of-office/working-location） gog calendar create primary \ --event-type focus-time \ --from 2025-01-15T13:00:00Z \ --to 2025-01-15T14:00:00Z gog calendar create primary \ --event-type out-of-office \ --from 2025-01-20 \ --to 2025-01-21 \ --all-day gog calendar create primary \ --event-type working-location \ --working-location-type office \ --working-office-label "HQ" \ --from 2025-01-22 \ --to 2025-01-23 # 专用快捷方式（相同事件类型，更具建议性的默认值） gog calendar focus-time --from 2025-01-15T13:00:00Z --to 2025-01-15T14:00:00Z gog calendar out-of-office --from 2025-01-20 --to 2025-01-21 --all-day gog calendar working-location --type office --office-label "HQ" --from 2025-01-22 --to 2025-01-23 # 添加 attendees 而不替换现有的 attendees/RSVP 状态 gog calendar update \ --add-attendee "alice@example.com,bob@example.com" gog calendar delete # 邀请 gog calendar respond --status accepted gog calendar respond --status declined gog calendar respond --status tentative gog calendar respond --status declined --send-updates externalOnly # 提议新时间（仅限浏览器流程；API 限制） gog calendar propose-time gog calendar propose-time --open gog calendar propose-time --decline --comment "Can we do 5pm?" # 空闲状态 gog calendar freebusy --calendars "primary,work@example.com" \ --from 2025-01-15T00:00:00Z \ --to 2025-01-16T00:00:00Z gog calendar conflicts --calendars "primary,work@example.com" \ --today # Today's conflicts ``` ### 时间 ``` gog time now gog time now --timezone UTC ``` ### Drive ``` # 列表和搜索 gog drive ls --max 20 gog drive ls --parent --max 20 gog drive ls --no-all-drives # Only list from "My Drive" gog drive search "invoice" --max 20 gog drive search "invoice" --no-all-drives gog drive search "mimeType = 'application/pdf'" --raw-query gog drive get # Get file metadata gog drive url # Print Drive web URL gog drive copy "Copy Name" # 上传和下载 gog drive upload ./path/to/file --parent gog drive upload ./path/to/file --replace # Replace file content in-place (preserves shared link) gog drive upload ./report.docx --convert gog drive upload ./chart.png --convert-to sheet gog drive upload ./report.docx --convert --name report.docx gog drive download --out ./downloaded.bin gog drive download --format pdf --out ./exported.pdf # Google Workspace files only gog drive download --format docx --out ./doc.docx gog drive download --format pptx --out ./slides.pptx # 整理 gog drive mkdir "New Folder" gog drive mkdir "New Folder" --parent gog drive rename "New Name" gog drive move --parent gog drive delete # Move to trash gog drive delete --permanent # Permanently delete # 权限 gog drive permissions gog drive share --to user --email user@example.com --role reader gog drive share --to user --email user@example.com --role writer gog drive share --to domain --domain example.com --role reader gog drive unshare --permission-id # 共享 drives（Team Drives） gog drive drives --max 100 ``` ### Docs / Slides / Sheets ``` # Docs gog docs info gog docs cat --max-bytes 10000 gog docs create "My Doc" gog docs create "My Doc" --file ./doc.md # Import markdown gog docs copy "My Doc Copy" gog docs export --format pdf --out ./doc.pdf gog docs list-tabs gog docs cat --tab "Notes" gog docs cat --all-tabs gog docs update --format markdown --content-file ./doc.md gog docs write --replace --markdown --file ./doc.md gog docs find-replace "old" "new" # Slides gog slides info gog slides create "My Deck" gog slides create-from-markdown "My Deck" --content-file ./slides.md gog slides copy "My Deck Copy" gog slides export --format pdf --out ./deck.pdf gog slides list-slides gog slides add-slide ./slide.png --notes "Speaker notes" gog slides update-notes --notes "Updated notes" gog slides replace-slide ./new-slide.png --notes "New notes" # Sheets gog sheets copy "My Sheet Copy" gog sheets export --format pdf --out ./sheet.pdf gog sheets format 'Sheet1!A1:B2' --format-json '{"textFormat":{"bold":true}}' --format-fields 'userEnteredFormat.textFormat.bold' gog sheets insert "Sheet1" rows 2 --count 3 gog sheets notes 'Sheet1!A1:B10' ``` ### 联系人 ``` # 个人联系人 gog contacts list --max 50 gog contacts search "Ada" --max 50 gog contacts get people/ gog contacts get user@example.com # Get by email # 其他联系人（您互动过的人） gog contacts other list --max 50 gog contacts other search "John" --max 50 # 创建和更新 gog contacts create \ --given "John" \ --family "Doe" \ --email "john@example.com" \ --phone "+1234567890" gog contacts update people/ \ --given "Jane" \ --email "jane@example.com" \ --birthday "1990-05-12" \ --notes "Met at WWDC" # 通过 JSON 更新（见 docs/contacts-json-update.md） gog contacts get people/ --json | \ jq '(.contact.urls //= []) | (.contact.urls += [{"value":"obsidian://open?vault=notes&file=People/John%20Doe","type":"profile"}])' | \ gog contacts update people/ --from-file - gog contacts delete people/ # Workspace 目录（需要 Google Workspace） gog contacts directory list --max 50 gog contacts directory search "Jane" --max 50 ``` ### 任务 ``` # Task lists gog tasks lists --max 50 gog tasks lists create