Google Calendar CLI：从终端管理日历事件

如何从终端使用 Google Calendar CLI？

连接一次 Google 账户，然后使用 nylas calendar list、nylas calendar events list、nylas calendar events create 和 nylas calendar availability find。无需创建 OAuth 凭证或编写 Calendar API 代码，即可获得终端 Google Calendar 工作流。

你想从命令行管理 Google Calendar。官方路径在你触碰任何事件之前需要 6 个步骤：

1. 在 Google Cloud Console 中创建 GCP 项目
2. 启用 Google Calendar API
3. 配置 OAuth 同意屏幕（外部应用需通过 Google 的品牌验证审核，敏感范围最长需要六周）
4. 创建 OAuth 2.0 凭证，或在需要域级委派时创建服务账号
5. 设置日历范围（读写使用 https://www.googleapis.com/auth/calendar，或更窄的 calendar.events）
6. 编写代码来交换令牌并调用 API

对于内部应用，GCP 配置本身很快。昂贵的是非内部应用的 OAuth 审核，加上每用户配额：Calendar API 默认限制为每个项目每分钟 600 次请求，因此重度自动化需要向 Google 申请配额。对于只想在终端查看下次会议的人来说，这些配置过于繁琐。

1. 辅助日历和所有权转移

Google Calendar 在账户生命周期事件中对辅助日历和主日历的处理方式不同。当员工离开 Google Workspace 域时，默认情况下其主日历会在 20 天后删除，但他们创建的辅助日历可能变成孤立状态。根据 Google Workspace 管理文档，管理员必须在删除用户账户前手动转移日历所有权。

Nylas CLI 可以列出某个授权可见的所有日历，并标记哪些是主日历、哪些是辅助日历。这对于离职前的所有权审计很有用。拥有 2-3 个共享日历的典型 Workspace 用户应每季度执行一次此盘点检查。

# 列出所有日历并标记非主日历
nylas calendar list --json | \
  jq -r '.[] | "\(.name) | primary=\(.is_primary) | id=\(.id)"'

# 从特定共享或辅助日历中拉取事件
nylas calendar events list --calendar cal_team_launch --days 14

对于重度使用 Workspace 的团队，盘点和所有权管理是日历运维的一部分。 Google Calendar 所有权变更指南 涵盖了离职工作流和编程化共享日历转移。

2. Workspace 管理员权限边界

Google Workspace 区分三种开发者经常混淆的认证模型：用户 OAuth 授权（Nylas CLI 使用的方式）、用于服务器间调用的服务账号，以及用于跨所有用户的管理员级访问的域级委派。根据 Google Workspace 认证概述，域级委派需要超级管理员为每个服务账号授权特定的 OAuth 范围。

Nylas CLI 在用户级 OAuth 范围内运行，涵盖已认证用户可见的个人和共享日历。对于需要同时读写 10 个以上员工日历的工作流，通过服务账号进行域级委派是 Google 的标准方式。Yahoo 和 iCloud 日历访问主要是个人账户问题，而 Google Workspace 日历管理则是租户策略和生命周期问题。

3. Google Meet 和事件类型工作流

Google Calendar 会自动为包含至少一位参与者的事件附加 Google Meet 会议详情。根据 Google 的 Workspace 博客，Google Meet 每天生成超过 1 亿个会议链接，因此大多数日历自动化脚本都需要处理 conferencing 字段。Nylas CLI 在 JSON 输出中公开这些 Meet 详情，以及专注时间、外出和工作地点元数据。

通过 Nylas CLI 创建包含参与者的事件会触发 Google 的自动会议功能。CLI 传递参与者列表和时间范围，Google Calendar 在服务端添加 Meet 链接。生成的事件对象包含一个 conferencing.details.url 字段，其中包含加入链接。

# 创建会议并让 Google 附加会议详情
nylas calendar events create \
  --title "Project Kickoff" \
  --start "2026-04-02 14:00" \
  --end "2026-04-02 15:00" \
  --participant alice@company.com \
  --participant bob@company.com

# 检查 Meet 链接和 Google 特有的元数据
nylas calendar events list --days 7 --json | \
  jq '.[] | {title: .title, meet: .conferencing, metadata: .metadata}'

4. 跨 Workspace 和个人日历的空闲状态查询

在 Google Calendar 上检查空闲状态需要使用日历 ID、时间范围和时区偏移量查询 FreeBusy API 端点。Nylas CLI 将此封装为一条命令，检查所有可见日历的空闲/忙碌时段。对于员工同时拥有个人 Gmail 和 Workspace 账户的团队，空闲状态检查需要考虑两个身份以避免重复预约。

nylas calendar availability check 命令返回已认证用户的空闲和忙碌时段。nylas calendar availability find 命令接受 2 个或更多参与者邮箱地址并查找共同可用时间。两个命令都支持 --start 和 --end 标志来限定搜索窗口。

# 查看自己的空闲/忙碌时段
nylas calendar availability check

# 在同事之间查找 30 分钟的空闲时段
nylas calendar availability find \
  --participants alice@company.com,bob@company.com \
  --duration 30

# 将搜索限定在某个日期范围内
nylas calendar availability find \
  --participants alice@company.com,bob@company.com \
  --duration 60 \
  --start "2026-04-01" \
  --end "2026-04-05"

5. Google Calendar 核心命令

Nylas CLI 为 Google Calendar 提供 4 个核心事件操作：列出、创建、更新和删除。这些命令直接映射到 Google Calendar API 的 Events 资源，但跳过了原始 API 所需的 40-80 行 Python 样板代码。无论目标日历是主日历、辅助日历还是共享的 Workspace 日历，每个命令的使用方式都相同。

nylas calendar events list 命令返回未来 N 天的事件，并支持 --show-tz 在每个事件旁显示时区信息。创建全天事件使用 --all-day 标志配合仅日期的 --start 值。更新操作需要事件 ID，可从列表命令的输出中获取。

# 列出即将到来的事件
nylas calendar events list --days 14 --show-tz

# 创建全天事件
nylas calendar events create \
  --title "Company Holiday" \
  --start "2026-04-10" \
  --all-day

# 重新安排现有事件
nylas calendar events update event_abc123 \
  --title "Sprint Planning (Moved)" \
  --start "2026-04-01 11:00" \
  --end "2026-04-01 12:00"

# 删除事件
nylas calendar events delete event_abc123

6. 用于脚本编写的 JSON 输出

每个 Nylas CLI 日历命令都支持 --json 标志，输出结构化 JSON 而非默认的表格格式。JSON 输出根据服务商不同，每个事件包含 15-20 个字段，涵盖开始/结束时间、参与者、会议信息、重复规则和服务商特有的元数据。将 JSON 通过管道传入 jq 可以实现过滤、分组和生成报告，无需编写完整脚本。

JSON 结构遵循 Nylas 事件架构，其中时间数据位于 when 键下，会议信息位于 conferencing 键下。Google Calendar 事件包含其他服务商不提供的额外元数据字段，如 color_id 和 event_type。以下示例展示了提取标题、按天统计事件数和过滤空闲时段的常见模式。

# 获取所有即将到来的事件（JSON 格式）
nylas calendar events list --days 7 --json

# 提取事件标题
nylas calendar events list --json | jq '.[].title'

# 统计本周每天的事件数
nylas calendar events list --days 7 --json | \
  jq 'group_by(.when.start_date) | map({date: .[0].when.start_date, count: length})'

# 仅提取空闲时段
nylas calendar availability check --json | \
  jq '.time_slots[] | select(.status == "free")'

Google Calendar API 与 Nylas CLI 对比

Google Calendar API 需要一个 GCP 项目、OAuth 同意屏幕和 40-80 行 Python 代码来列出事件。Nylas CLI 用一条命令即可实现相同结果。以下对比涵盖 7 个维度，从初始配置时间到基本日历 CRUD 操作所需的代码行数。

Google Calendar 特有技巧

Google Calendar 有几个 Outlook、Yahoo 或 iCloud 日历中不存在的服务商特有功能。包括 11 个数字颜色标签、基于 RRULE 的重复事件展开、自动 Google Meet 链接生成，以及专注时间和工作地点等事件类型。理解这 4 个领域有助于在通过 Nylas CLI 编写 Google Calendar 数据脚本时避免意外。

颜色标签

Google Calendar 为事件分配 1 到 11 的数字颜色 ID，每个数字对应 Google 调色板中的一个命名颜色（例如，颜色 ID 11 是"Tomato"）。使用 --json 列出事件时，color_id 字段出现在元数据对象中。按颜色 ID 过滤对于按项目或优先级分类事件的脚本很有用。

# 列出特定颜色的事件（例如 "Tomato" = color_id 11）
nylas calendar events list --json | \
  jq '.[] | select(.metadata.color_id == "11") | .title'

重复事件

Google Calendar 使用 RFC 5545 中定义的 RRULE 模式存储重复事件。例如，每周例会作为单个主事件存储，带有类似 FREQ=WEEKLY;BYDAY=MO 的 RRULE，Google 将其展开为各个独立的实例。当 Nylas CLI 列出事件时，每个实例都显示为单独的事件对象。master_event_id 字段将每个实例链接回原始主事件，这对于批量编辑整个系列很有用。

# 列出事件并过滤特定重复系列
nylas calendar events list --json | \
  jq '.[] | select(.master_event_id == "event_abc123") | {title, start: .when.start_time}'

Google Meet 链接

Google Calendar 会自动为通过 Google Workspace 或个人 Gmail 账户创建的包含至少 1 位参与者的事件生成 Meet 加入链接。会议数据出现在 JSON 事件对象的 conferencing 字段中。没有参与者的事件（如全天提醒或专注时间块）不会收到 Meet 链接。以下 jq 过滤器仅提取附有会议信息的事件。

# 查找包含 Google Meet 链接的事件
nylas calendar events list --json | \
  jq '.[] | select(.conferencing != null) | {title, meet: .conferencing.details.url}'

工作地点和专注时间日历

Google Calendar 引入了 3 种其他服务商不支持的特殊事件类型：专注时间、外出和工作地点。这些事件类型对空闲状态的影响不同于常规会议。例如，专注时间块将用户标记为忙碌，但会自动拒绝新的会议邀请。外出事件会自动拒绝并向组织者发送自定义消息。如果你的日程安排脚本将所有事件都视为常规会议，就会误解这些 Google 特有的类型。检查 JSON 输出中的 metadata 和 status 字段来区分它们。

# 检查 Google 特有的事件元数据
nylas calendar events list --days 7 --json | \
  jq '.[] | {title: .title, status: .status, metadata: .metadata}'

下一步

本指南涵盖了 Google Calendar 事件 CRUD、空闲状态查询以及 Meet 链接和专注时间块等服务商特有功能。Nylas CLI 使用相同的命令语法支持 6 个日历服务商，因此大多数模式可直接应用于 Outlook、Yahoo 和 iCloud 日历。

• Nylas CLI 入门 -- 安装、连接 Google 账户并运行第一条命令
• 从终端管理日历事件 -- DST 感知调度、时区锁定和 AI 驱动的会议查找器
• 邮件 CLI 工具对比 -- 对比同样需要日历访问的终端邮件工具
• AI 智能体 CLI 用于邮件和日历 -- 将日历命令作为 JSON 工具暴露给 LLM 智能体
• 从命令行列出 Gmail 邮件 -- 无需 Google API 配置即可阅读和搜索收件箱
• 从终端发送邮件 -- 在 CLI 中撰写和发送邮件
• Google Calendar 所有权变更 -- 孤立日历 4 月 27 日删除，新的转移 API 6 月推出
• Google Calendar API 分页与同步 -- nextPageToken、syncToken、410 Gone 恢复和重复事件展开
• 通过 MCP 为 AI 智能体提供邮件访问 -- 将 Claude 或 Cursor 连接到你的日历和邮箱
• 跨服务商同步日历 -- ICS、CalDAV 和基于 API 的日历同步对比
• 最佳 CLI 日历工具对比 -- gcalcli、khal、calcurse、remind 和 Nylas CLI
• 完整命令参考 -- 每个日历标志和子命令