pp-cal-com

Cal.com — Printing Press 命令行工具

前提条件：安装 CLI

此技能使用 cal-com-pp-cli 二进制文件。**调用此技能中的任何命令之前，必须先确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install cal-com --cli-only
   

2. 验证：cal-com-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/productivity/cal-com/cmd/cal-com-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法通过 $PATH 找到二进制文件目录。在验证成功之前，不要继续执行技能命令。

何时使用此 CLI

只要 Agent 需要读取或修改 Cal.com 日历，就使用 cal-com-pp-cli，避免在 API 所需的多次调用流程上耗费上下文，尤其是预订和改期操作。本地存储可让“我的日历上有什么”“我什么时候有空”“谁的工作量过重”和“有哪些冲突”等问题得到近乎即时的离线回答。组合式 book 和 reschedule next 命令适用于事务性预订；其他需求则可通过与端点镜像的功能覆盖来处理。

独特功能

这些功能是此 API 的其他任何工具都不具备的。

组合式预订流程

• book — 通过一次组合调用，为某个参与者预订你的某个事件类型——检查时段、可选预留、创建、可选确认。

  适用于主持人为参与者安排日历时（管理员引导、招聘人员预填、测试固件）。对于参与者自行选择时间的常规流程，请改为分享 link list 生成的 URL。

  cal-com-pp-cli book --event-type-id 96531 --start 2026-05-06T17:00:00Z --attendee-name Guest --attendee-email [email protected] --dry-run
  

• slots find — 通过一次调用，查找多个事件类型 ID 中最早可用的时段，并按开始时间排序。

  如果你不确定哪个事件类型合适，可使用此命令——让调用方从合并后的排序列表中选择。

  cal-com-pp-cli slots find --event-type-ids 96531 --start tomorrow --end "tomorrow 23:59" --json
  

• reschedule next — 在截止时间之后，将现有预订改到同一事件类型的下一个可用时段。

  适用于临时改期——一个命令即可代替三个命令，并提供安全的试运行模式。

  cal-com-pp-cli reschedule next --uid <booking-uid> --after tomorrow --dry-run
  

不断积累的本地状态

• agenda — 从本地存储中读取指定时间范围内的即将开始的预订——今天、本周或任意时长。

  只要 Agent 需要了解“我的日历上有什么”，就使用此命令；可通过一个命令查询任何时间范围。

  cal-com-pp-cli agenda --window today --json --select id,start,title,attendees
  

• analytics no-show — 统计指定时间范围内的未到场、取消、数量和密度指标。analytics 下的相关子命令包括：bookings（数量）、cancellations、no-show、density。速率类命令的 --by 参数可接受 event-type、attendee 或 weekday；analytics density --unit hour 可添加每小时热力图。

  可用于容量规划、未到场趋势分析或跟进参与者——这些问题都无法通过单次 API 调用解答。

  cal-com-pp-cli analytics no-show --window 90d --by attendee --json
  

• conflicts — 检测指定时间范围内相互重叠的预订，并报告时间范围存在交集的预订对。读取本地存储，不调用 API。

  发送确认信息之前，或批量改期之后，可运行此命令——它能发现 API 不会提示的重复预订。

  cal-com-pp-cli conflicts --window 7d --json
  

• gaps — 查找日程中尚未预订的可用时段，并按最小时间段长度筛选。

  可用于容量规划——它回答的是“我什么时候可以开会”，而不是“我有哪些待办”。

  cal-com-pp-cli gaps --window 7d --min-minutes 60 --json
  

• workload — 统计指定时间范围内团队成员的预订分布，找出工作量过重或利用不足的主持人。

  可用于调整轮询分配，或在未到场问题显现之前发现主持人的过劳迹象。

  cal-com-pp-cli workload --team-id 42 --window 30d --json
  

• event-types stale — 查找过去 N 天内没有任何预订的事件类型，可作为删除候选项。

  可用于季度清理，避免可预订的事件类型不断偏离实际需求。

  cal-com-pp-cli event-types stale --days 90 --json
  

主机控制界面

• link create — 在你的 Cal.com 账户上创建新的可预约链接（活动类型）；输出可直接分享的 cal.com// URL。

  这是主机最主要的创作行为。与会者通过可预约链接预约时间；使用此命令即可创建链接。

  cal-com-pp-cli link create --slug 30min --length 30 --title "30 Min Meeting"
  

• link list — 列出你拥有的所有可预约链接，并预先生成完整 URL，方便复制分享。

  用于查看已有链接并获取 URL，无需手动拼接 cal.com//。

  cal-com-pp-cli link list --json
  

• ooo set — 将你设置为在指定日期范围内不在办公室，以便 Cal.com 在搜索时段时排除这段时间。

  要去度假？生病了？运行一次此命令，就不会再收到预约。可选的 --redirect-to-user 参数会将预约转给队友（仅适用于轮询分配）。

  cal-com-pp-cli ooo set --start 2026-05-12 --end 2026-05-18 --reason vacation --notes "Hawaii trip"
  

• ooo list — 列出你当前和即将开始的 OOO 条目。

  cal-com-pp-cli ooo list --json
  

面向 Agent 的基础设施

• webhooks coverage — 根据规范集合审计已注册的 Webhook 触发器，并报告没有订阅者的生命周期事件。

  每次添加新的自动化时都运行此命令，以发现遗漏的触发器，例如 BOOKING_NO_SHOW_UPDATED，避免问题发生。

  cal-com-pp-cli webhooks coverage --json
  

命令参考

api-keys — 管理 api keys

• cal-com-pp-cli api-keys — 生成新的 API key 并删除当前密钥。提供要刷新的 API key，作为 Bearer token 放入 Authorization...

bookings — 管理预约

• cal-com-pp-cli bookings create — POST /v2/bookings 用于创建常规预约、循环预约和即时预约。请求正文...
• cal-com-pp-cli bookings get — 请确保传入 Headers 部分提到的 cal-api-version 标头值。未传入...
• cal-com-pp-cli bookings get-bookinguid — :bookingUid 可以是：1. 常规预约的 uid；2. 某个循环预约实例的 uid；3. ...
• cal-com-pp-cli bookings get-by-seat-uid — 通过席位引用 UID 获取指定席位的预约。当你持有席位预约的 seatUid 时，此功能很有用...

cal-com-auth — 管理 cal com 身份验证

• cal-com-pp-cli cal-com-auth — 符合 RFC 6749 的令牌端点。在请求正文中传入 client_id（第 2.3.1 节）。使用 grant_type...

cal-com-auth-2 — 管理 cal com 身份验证 2

• cal-com-pp-cli cal-com-auth-2 <clientId> — 返回指定客户端 ID 对应的 OAuth2 客户端信息

calendars — 管理日历

• cal-com-pp-cli calendars check-ics-feed — 使用 OAuth 访问令牌访问时，需要 APPS_READ 范围。
• cal-com-pp-cli calendars create-ics-feed — 使用 OAuth 访问令牌访问时，需要 APPS_WRITE 范围。
• cal-com-pp-cli calendars get — 使用 OAuth 访问令牌访问时，需要 APPS_READ 范围。
• cal-com-pp-cli calendars get-busy-times — 从日历获取忙碌时段。请求 URL 示例：`https://api.cal.com/v2/calendars/busy-times?timeZone=Europe%2...

conferencing — 管理会议

• cal-com-pp-cli conferencing get-default — 使用 OAuth 访问令牌访问时，需要 APPS_READ 范围。
• cal-com-pp-cli conferencing list-installed-apps — 使用 OAuth 访问令牌访问时，需要 APPS_READ 范围。

credits — 管理额度

• cal-com-pp-cli credits charge — 对已完成的 AI Agent 交互扣除额度。使用 externalRef 保证幂等性，防止重复扣费。
• cal-com-pp-cli credits get-available — 检查已认证用户（或其组织/团队）是否有可用额度，并返回当前余额。

destination-calendars — 管理目标日历

• cal-com-pp-cli destination-calendars — 使用 OAuth 访问令牌访问时，需要 APPS_WRITE 范围。

event-types — 管理活动类型

• cal-com-pp-cli event-types create — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。未传入……
• cal-com-pp-cli event-types delete — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。未传入……
• cal-com-pp-cli event-types get — 仅当提供了身份验证，且该身份验证属于事件类型所有者时，才会返回隐藏的事件类型。使用……
• cal-com-pp-cli event-types get-by-id — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。未传入……
• cal-com-pp-cli event-types update — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。未传入……

我 — 管理个人信息

• cal-com-pp-cli me clear-my-booking-limits — 移除已通过身份验证用户的所有全局预订限制。仅适用于组织成员——非组织……
• cal-com-pp-cli me get — 如果使用 OAuth 访问令牌访问，则需要 PROFILE_READ 范围。
• cal-com-pp-cli me get-my-booking-limits — 返回已通过身份验证用户的全局预订限制。未设置的边界将返回 null。仅适用于……
• cal-com-pp-cli me update — 更新已通过身份验证用户的个人资料。更改电子邮件需要验证，且主电子邮件保持不变……
• cal-com-pp-cli me update-my-booking-limits — 部分更新已通过身份验证用户的全局预订限制。仅更新请求正文中包含的字段……
• cal-com-pp-cli me user-ooocontroller-create-my-ooo — 如果使用 OAuth 访问令牌访问，则需要 SCHEDULE_WRITE 范围。
• cal-com-pp-cli me user-ooocontroller-delete-my-ooo — 如果使用 OAuth 访问令牌访问，则需要 SCHEDULE_WRITE 范围。
• cal-com-pp-cli me user-ooocontroller-get-my-ooo — 如果使用 OAuth 访问令牌访问，则需要 SCHEDULE_READ 范围。
• cal-com-pp-cli me user-ooocontroller-update-my-ooo — 如果使用 OAuth 访问令牌访问，则需要 SCHEDULE_WRITE 范围。

notifications — 管理通知

• cal-com-pp-cli notifications subscriptions-register — 注册应用推送订阅
• cal-com-pp-cli notifications subscriptions-remove — 移除应用推送订阅

oauth — 管理 oauth

oauth-clients — 管理 oauth 客户端

• cal-com-pp-cli oauth-clients create — 这些端点已弃用，未来将被移除。
• cal-com-pp-cli oauth-clients delete — 这些端点已弃用，未来将被移除。
• cal-com-pp-cli oauth-clients get — 这些端点已弃用，未来将被移除。
• cal-com-pp-cli oauth-clients get-by-id — 这些端点已弃用，未来将被移除。
• cal-com-pp-cli oauth-clients update — 这些端点已弃用，未来将被移除。

organizations — 管理组织

routing-forms — 管理路由表单

schedules — 管理日程

• cal-com-pp-cli schedules create — 为经过身份验证的用户创建日程。创建日程的目的是让活动类型可以在……中使用
• cal-com-pp-cli schedules delete — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。若未传入……
• cal-com-pp-cli schedules get — 获取经过身份验证的用户的所有日程。请务必传入 Headers 部分中提到的 cal-api-version 标头值……
• cal-com-pp-cli schedules get-default — 获取经过身份验证的用户的默认日程。请务必传入 Headers 部分中提到的 cal-api-version 标头……
• cal-com-pp-cli schedules get-scheduleid — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。若未传入……
• cal-com-pp-cli schedules update — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。若未传入……

selected-calendars — 管理已选日历

• cal-com-pp-cli selected-calendars add — 如果使用 OAuth 访问令牌进行访问，则需要 APPS_WRITE 作用域。
• cal-com-pp-cli selected-calendars delete — 如果使用 OAuth 访问令牌进行访问，则需要 APPS_WRITE 作用域。

slots — 管理时段

• cal-com-pp-cli slots delete-reserved — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。若未传入……
• cal-com-pp-cli slots get-available — 获取个人用户活动类型的可用时段有 4 种方式：1. 按活动类型 ID。示例……
• cal-com-pp-cli slots get-reserved — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。若未传入……
• cal-com-pp-cli slots reserve — 在一段时间内将某个时段设为不可供他人预订。如果使用 OAuth 进行身份验证……
• cal-com-pp-cli slots update-reserved — 请务必传入 Headers 部分中提到的 cal-api-version 标头值。若未传入……

stripe — 管理 stripe

• cal-com-pp-cli stripe check — 检查 Stripe 连接
• cal-com-pp-cli stripe redirect — 获取 Stripe 连接 URL
• cal-com-pp-cli stripe save — 保存 Stripe 凭据

teams — 管理团队

• cal-com-pp-cli teams create — 如果使用 OAuth 访问令牌进行访问，则需要 TEAM_PROFILE_WRITE 作用域。
• cal-com-pp-cli teams delete — 如果使用 OAuth 访问令牌进行访问，则需要 TEAM_PROFILE_WRITE 作用域。
• cal-com-pp-cli teams get — 如果使用 OAuth 访问令牌进行访问，则需要 TEAM_PROFILE_READ 作用域。
• cal-com-pp-cli teams get-teamid — 如果使用 OAuth 访问令牌进行访问，则需要 TEAM_PROFILE_READ 作用域。
• cal-com-pp-cli teams update — 如果使用 OAuth 访问令牌进行访问，则需要 TEAM_PROFILE_WRITE 作用域。

verified-resources — 管理已验证资源

• cal-com-pp-cli verified-resources user-get-verified-email-by-id — 使用 OAuth 访问令牌访问时，需要 VERIFIED_RESOURCES_READ 范围。
• cal-com-pp-cli verified-resources user-get-verified-emails — 使用 OAuth 访问令牌访问时，需要 VERIFIED_RESOURCES_READ 范围。
• cal-com-pp-cli verified-resources user-get-verified-phone-by-id — 使用 OAuth 访问令牌访问时，需要 VERIFIED_RESOURCES_READ 范围。
• cal-com-pp-cli verified-resources user-get-verified-phone-numbers — 使用 OAuth 访问令牌访问时，需要 VERIFIED_RESOURCES_READ 范围。
• cal-com-pp-cli verified-resources user-request-email-verification-code — 向电子邮件地址发送验证码。使用 OAuth 访问令牌访问时，需要 VERIFIED_RESOURCES_WRITE...
• cal-com-pp-cli verified-resources user-request-phone-verification-code — 向电话号码发送验证码。使用 OAuth 访问令牌访问时，需要...
• cal-com-pp-cli verified-resources user-verify-email — 使用验证码验证电子邮件地址。使用 OAuth 访问令牌访问时，需要 VERIFIED_RESOURCES_WRITE 范围。
• cal-com-pp-cli verified-resources user-verify-phone-number — 使用验证码验证电话号码。使用 OAuth 访问令牌访问时，需要 VERIFIED_RESOURCES_WRITE 范围...

webhooks — 管理 Webhook

• cal-com-pp-cli webhooks create — 使用 OAuth 访问令牌访问时，需要 WEBHOOK_WRITE 范围。
• cal-com-pp-cli webhooks delete — 使用 OAuth 访问令牌访问时，需要 WEBHOOK_WRITE 范围。
• cal-com-pp-cli webhooks get — 获取已认证用户的分页 Webhook 列表。使用 OAuth 访问令牌访问时，需要...
• cal-com-pp-cli webhooks get-webhookid — 使用 OAuth 访问令牌访问时，需要 WEBHOOK_READ 范围。
• cal-com-pp-cli webhooks update — 使用 OAuth 访问令牌访问时，需要 WEBHOOK_WRITE 范围。

查找合适的命令

知道要做什么，但不确定该用哪个命令时，可以直接询问 CLI：

cal-com-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精心整理的功能索引中匹配最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信匹配项——请改用 --help 或缩小查询范围。

使用示例

创建可预约链接并分享其 URL

cal-com-pp-cli link create --slug 30min --length 30 --title "30 Min Meeting"
cal-com-pp-cli link list --json --select links.slug,links.bookable_url

link create 会预先生成可预约的 URL（cal.com//）；link list 会显示该主机发布的所有链接。

将自己标记为不在办公室

cal-com-pp-cli ooo set --start 2026-05-12 --end 2026-05-18 --reason vacation --notes "Hawaii trip"
cal-com-pp-cli ooo list --json

OOO 条目生效期间，Cal.com 会在时段搜索中排除这段时间，因此不会有人预约你。

从本地存储获取今天的日程

cal-com-pp-cli agenda --window today --json --select bookings.uid,bookings.title,bookings.start,bookings.attendees

只返回日程数据中的四个必需字段，让 Agent 在处理深度嵌套的预约数据时保持上下文精简。

按开始时间排序的跨活动类型时段搜索

cal-com-pp-cli slots find --event-type-ids 96531 --start tomorrow --end "tomorrow 23:59" --json --first-only

针对每个活动类型 ID 并行调用 /v2/slots；只返回最早的时段。

按参会者统计未出席率，用于容量规划

cal-com-pp-cli analytics no-show --window 90d --by attendee --json

在已同步的预约数据上执行本地 SQL 聚合；不会调用 API。

添加自动化之前审计 Webhook 覆盖情况

cal-com-pp-cli webhooks coverage --json

将你注册的触发器与 Cal.com 标准生命周期事件集进行比较，并指出缺少订阅者的事件。

将预约重新安排到下一个空闲时段

cal-com-pp-cli reschedule next --uid <booking-uid> --after tomorrow --dry-run

一条组合命令即可替代三条命令；--dry-run 会打印计划的调整，不会提交更改。

身份验证设置

Cal.com 使用带有 cal_live_（正式环境）或 cal_test_（测试环境）前缀的 bearer token。在环境中设置 CAL_COM_TOKEN，或运行一次 auth set-token。CLI 也会通过相同的 Authorization 标头接受托管用户访问令牌和 OAuth 访问令牌。客户端会自动处理按资源固定 API 版本的 cal-api-version。

运行 cal-com-pp-cli doctor 以验证设置。

Agent 模式

在任意命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留一部分字段。点分路径会深入嵌套结构；数组会逐项遍历。对于冗长的 API，这对于控制上下文大小至关重要：

  cal-com-pp-cli bookings get --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求但不发送

• 支持离线 — 有本地 SQLite 存储时，同步/搜索命令可以使用该存储

• 非交互式 — 从不提示输入，每项输入都必须通过标志传入

响应封装

从本地存储或 API 读取数据的命令，会将输出封装在来源信息中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并通过 .meta.source 判断数据来自实时还是本地。只有当 stdout 连接到终端时，才会将便于阅读的 N results (live) 摘要输出到 stderr；通过管道接收的程序或 Agent 消费者会在 stdout 上获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

cal-com-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
cal-com-pp-cli feedback --stdin < notes.txt
cal-com-pp-cli feedback list --json --limit 10

条目会保存在本地的 ~/.cal-com-pp-cli/feedback.jsonl 中。除非设置了 CAL_COM_FEEDBACK_ENDPOINT，且传入了 --send 或设置了 CAL_COM_FEEDBACK_AUTO_SEND=true，否则不会通过 POST 发送。默认行为仅保存在本地。

记录让你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：真正有价值的正是这些记录的累积。

输出传递

每个命令都接受 --deliver <sink>。输出会写入指定的目标位置，也可以同时写入 stdout，Agent 因此无需手动通过管道传递命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

遇到未知方案时会拒绝执行，并返回结构化错误，指出受支持的方案。Webhook 请求失败时会返回非零退出码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。当定时运行的 Agent 每次都以相同配置调用同一命令时，可以使用配置——这就是 HeyGen 的“Beacon”模式。

cal-com-pp-cli profile save briefing --json
cal-com-pp-cli --profile briefing bookings get
cal-com-pp-cli profile list --json
cal-com-pp-cli profile show briefing
cal-com-pp-cli profile delete briefing --yes

显式标志的优先级始终高于配置值；配置值的优先级高于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 cal-com-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并添加 --agent）

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/productivity/cal-com/cmd/cal-com-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add cal-com-pp-mcp -- cal-com-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which cal-com-pp-cli 如果未找到，则提出安装选项（参见此技能顶部的先决条件）。
2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   cal-com-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，可查看子命令帮助：cal-com-pp-cli <command> --help。