pp-cal-com

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cal.com — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

cal-com-pp-cli

binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer:

bash

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

Verify:
```
cal-com-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):

bash

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

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

本技能基于

cal-com-pp-cli

可执行文件运行。在调用本技能的任何命令前，必须确认CLI已安装。如果未安装，请先执行以下步骤：

通过Printing Press安装器安装：

bash

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

验证安装：
```
cal-com-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等情况），可以直接通过Go安装（要求Go 1.23及以上版本）：

bash

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

如果安装后执行

--version

提示“command not found”，说明安装程序未将可执行文件添加到

$PATH

中。请在验证成功前不要执行技能命令。

When to Use This CLI

何时使用此CLI

Reach for cal-com-pp-cli whenever an agent needs to read or mutate a Cal.com calendar without burning context on the multi-call dance the API requires for booking and rescheduling. The local store makes 'what's on my calendar', 'when am I free', 'who is overloaded', and 'where are my conflicts' near-instant offline answers. The composed

book

and

reschedule next

commands are the right tools for transactional bookings; the endpoint-mirror coverage is there for everything else.

当Agent需要读取或修改Cal.com日历，且不想因预订和重新安排操作需要多次调用API而消耗上下文时，可以使用cal-com-pp-cli。本地存储让“我的日历今天有什么安排”“我什么时候有空”“谁的日程已满”“我的日程冲突在哪里”这类问题能快速得到离线答案。组合式的

book

和

reschedule next

命令是处理事务性预订的理想工具；而端点镜像覆盖则可处理其他所有操作。

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.

这些功能是其他同类型API工具所不具备的。

Composed booking flows

组合式预订流程

book
— Schedule an attendee onto one of your event types in a single composed call — slot check, optional reservation, create, optional confirm.
For the host scripting an attendee onto their calendar (admin onboarding, recruiter pre-fill, test fixtures). For the normal flow where the attendee picks their own time, share a URL from
link list
instead.
bash
```
cal-com-pp-cli book --event-type-id 96531 --start 2026-05-06T17:00:00Z --attendee-name Guest --attendee-email guest@example.com --dry-run
```
slots find
— Find first available slots across multiple event-type IDs in one call, ranked by start time.
Use this when you don't know which event type fits — let the caller pick from a ranked merged list.
bash
```
cal-com-pp-cli slots find --event-type-ids 96531 --start tomorrow --end "tomorrow 23:59" --json
```
reschedule next
— Move an existing booking to the next available slot for the same event type, after a cutoff.
Use this for last-minute bumps — one command instead of three, with dry-run safety.
bash
```
cal-com-pp-cli reschedule next --uid <booking-uid> --after tomorrow --dry-run
```

book
— 通过单次组合调用将参会者安排到你的某类活动中，包含时段检查、可选预留、创建、可选确认等步骤。
适用于主持人将参会者手动添加到日程的场景（如管理员入职安排、招聘人员预填信息、测试数据准备）。如果是参会者自行选择时段的常规流程，请使用
link list
生成的分享链接。
bash
```
cal-com-pp-cli book --event-type-id 96531 --start 2026-05-06T17:00:00Z --attendee-name Guest --attendee-email guest@example.com --dry-run
```
slots find
— 单次调用查询多个活动类型ID的首个可用时段，并按开始时间排序。
当你不确定哪种活动类型合适时使用此命令，让调用者从排序后的合并列表中选择。
bash
```
cal-com-pp-cli slots find --event-type-ids 96531 --start tomorrow --end "tomorrow 23:59" --json
```
reschedule next
— 将现有预订移至同一活动类型在截止时间后的下一个可用时段。
适用于临时调整安排——一个命令替代三个步骤，且支持
dry-run
安全预览。
bash
```
cal-com-pp-cli reschedule next --uid <booking-uid> --after tomorrow --dry-run
```

Local state that compounds

可累积的本地状态

agenda
— Upcoming bookings in a window — today, this week, or any duration — read from the local store.
Use this whenever an agent needs 'what's on my calendar'; single command across any time window.
bash
```
cal-com-pp-cli agenda --window today --json --select id,start,title,attendees
```
analytics no-show
— No-show, cancellation, volume, and density metrics over a window. Sister subcommands under analytics: bookings (volume), cancellations, no-show, density. --by accepts event-type, attendee, or weekday on the rate commands; analytics density --unit hour adds hourly heatmaps.
Use this for capacity planning, no-show trend analysis, or attendee follow-up — answers no single API call provides.
bash
```
cal-com-pp-cli analytics no-show --window 90d --by attendee --json
```
conflicts
— Detects overlapping bookings within a time window — pairs whose time ranges intersect get reported. Reads the local store, no API call.
Run before sending confirmations or after a bulk reschedule — surfaces double-bookings the API silently allows.
bash
```
cal-com-pp-cli conflicts --window 7d --json
```
gaps
— Finds open windows in your schedule that are available but unbooked, filtered by minimum block size.
Use this for capacity planning — answers 'when can I take a meeting' rather than 'what's on my plate'.
bash
```
cal-com-pp-cli gaps --window 7d --min-minutes 60 --json
```
workload
— Booking distribution across team members over a window — surfaces overloaded vs underutilized hosts.
Use this for round-robin tuning or to spot host burnout before it shows up as no-shows.
bash
```
cal-com-pp-cli workload --team-id 42 --window 30d --json
```
event-types stale
— Event types with zero bookings in the last N days — candidates for removal.
Use this for quarterly cleanup — keeps your bookable surface from drifting.
bash
```
cal-com-pp-cli event-types stale --days 90 --json
```

agenda
— 从本地存储读取指定时间窗口（今日、本周或任意时长）内的 upcoming 预订。
当Agent需要查看“我的日历安排”时使用此命令，单次命令即可覆盖任意时间窗口。
bash
```
cal-com-pp-cli agenda --window today --json --select id,start,title,attendees
```
analytics no-show
— 统计指定时间窗口内的缺席、取消、预订量和密度指标。analytics下的子命令还包括bookings（预订量）、cancellations（取消量）、no-show（缺席）、density（密度）。在比率类命令中，
```
--by
```
参数支持按活动类型、参会者或工作日统计；
```
analytics density --unit hour
```
可添加小时热力图。
适用于容量规划、缺席趋势分析或参会者跟进——这些信息无法通过单次API调用获取。
bash
```
cal-com-pp-cli analytics no-show --window 90d --by attendee --json
```
conflicts
— 检测指定时间窗口内的重叠预订，报告时间范围相交的预订对。读取本地存储，无需调用API。
在发送确认信息前或批量重新安排后运行此命令——可发现API默认允许的重复预订情况。
bash
```
cal-com-pp-cli conflicts --window 7d --json
```
gaps
— 查找日程中可用但未被预订的空闲窗口，可按最小时长过滤。
适用于容量规划——回答“我什么时候可以安排会议”而非“我有哪些待办事项”。
bash
```
cal-com-pp-cli gaps --window 7d --min-minutes 60 --json
```
workload
— 统计指定时间窗口内团队成员的预订分布情况，识别日程过满或利用不足的主持人。
适用于循环调度优化，或在缺席情况出现前发现主持人 burnout 迹象。
bash
```
cal-com-pp-cli workload --team-id 42 --window 30d --json
```
event-types stale
— 查找最近N天内无预订的活动类型，这些类型可考虑移除。
适用于季度清理——保持可预订活动列表的简洁性。
bash
```
cal-com-pp-cli event-types stale --days 90 --json
```

Host control surface

主持人控制面板

link create
— Create a new bookable link (event type) on your Cal.com account; prints the cal.com/<your-username>/<slug> URL ready to share.
The host's primary creative act. Bookable links are how attendees book time; this is the command to make one.
bash
```
cal-com-pp-cli link create --slug 30min --length 30 --title "30 Min Meeting"
```
link list
— List every bookable link you own with the full URL pre-rendered for copy-share.
Use this to see what links you have and grab their URLs without hand-composing cal.com/<user>/<slug>.
bash
```
cal-com-pp-cli link list --json
```
ooo set
— Mark yourself out-of-office for a date range so Cal.com excludes the period from slot search.
Going on vacation? Sick? Run this once and stop getting booked. Optional --redirect-to-user forwards bookings to a teammate (round-robin only).
bash
```
cal-com-pp-cli ooo set --start 2026-05-12 --end 2026-05-18 --reason vacation --notes "Hawaii trip"
```
ooo list
— List your active and upcoming OOO entries.
bash
```
cal-com-pp-cli ooo list --json
```

link create
— 在你的Cal.com账户中创建新的可预订链接（活动类型），并输出可直接分享的cal.com/<your-username>/<slug>链接。
这是主持人创建可预订活动的核心操作。参会者通过可预订链接预约时间，此命令用于生成这类链接。
bash
```
cal-com-pp-cli link create --slug 30min --length 30 --title "30 Min Meeting"
```
link list
— 列出你拥有的所有可预订链接，并预渲染完整URL以便复制分享。
用于查看已有的链接，无需手动拼接cal.com/<user>/<slug>即可获取URL。
bash
```
cal-com-pp-cli link list --json
```
ooo set
— 标记你在指定日期范围内处于休假状态，Cal.com会在时段搜索中排除该时间段。
休假或生病时运行此命令，避免被安排预订。可选参数
--redirect-to-user
可将预订转交给团队成员（仅支持循环调度模式）。
bash
```
cal-com-pp-cli ooo set --start 2026-05-12 --end 2026-05-18 --reason vacation --notes "Hawaii trip"
```
ooo list
— 列出当前和即将到来的休假记录。
bash
```
cal-com-pp-cli ooo list --json
```

Agent-native plumbing

Agent原生管道

webhooks coverage
— Audits registered webhook triggers against the canonical set and reports lifecycle events with no subscriber.
Run this whenever you add a new automation — surfaces missed triggers like BOOKING_NO_SHOW_UPDATED before they bite.
bash
```
cal-com-pp-cli webhooks coverage --json
```

webhooks coverage
— 检查已注册的Webhook触发器与标准集合的匹配情况，并报告无订阅者的生命周期事件。
在添加新自动化时运行此命令——提前发现如BOOKING_NO_SHOW_UPDATED这类遗漏的触发器。
bash
```
cal-com-pp-cli webhooks coverage --json
```

Command Reference

命令参考

api-keys — Manage api keys

```
cal-com-pp-cli api-keys
```
— Generate a new API key and delete the current one. Provide API key to refresh as a Bearer token in the Authorization...

bookings — Manage bookings

```
cal-com-pp-cli bookings create
```
— POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies...
```
cal-com-pp-cli bookings get
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
```
cal-com-pp-cli bookings get-bookinguid
```
—
```
:bookingUid
```
can be 1. uid of a normal booking 2. uid of one of the recurring booking recurrences 3. uid of...
```
cal-com-pp-cli bookings get-by-seat-uid
```
— Get a seated booking by its seat reference UID. This is useful when you have a seatUid from a seated booking and...

cal-com-auth — Manage cal com auth

```
cal-com-pp-cli cal-com-auth
```
— RFC 6749-compliant token endpoint. Pass client_id in the request body (Section 2.3.1). Use grant_type...

cal-com-auth-2 — Manage cal com auth 2

```
cal-com-pp-cli cal-com-auth-2 <clientId>
```
— Returns the OAuth2 client information for the given client ID

calendars — Manage calendars

```
cal-com-pp-cli calendars check-ics-feed
```
— If accessed using an OAuth access token, the
```
APPS_READ
```
scope is required.
```
cal-com-pp-cli calendars create-ics-feed
```
— If accessed using an OAuth access token, the
```
APPS_WRITE
```
scope is required.
```
cal-com-pp-cli calendars get
```
— If accessed using an OAuth access token, the
```
APPS_READ
```
scope is required.
```
cal-com-pp-cli calendars get-busy-times
```
— Get busy times from a calendar. Example request URL is `https://api.cal.com/v2/calendars/busy-times?timeZone=Europe%2...

conferencing — Manage conferencing

```
cal-com-pp-cli conferencing get-default
```
— If accessed using an OAuth access token, the
```
APPS_READ
```
scope is required.
```
cal-com-pp-cli conferencing list-installed-apps
```
— If accessed using an OAuth access token, the
```
APPS_READ
```
scope is required.

credits — Manage credits

```
cal-com-pp-cli credits charge
```
— Charge credits for a completed AI agent interaction. Uses externalRef for idempotency to prevent double-charging.
```
cal-com-pp-cli credits get-available
```
— Check if the authenticated user (or their org/team) has available credits and return the current balance.

destination-calendars — Manage destination calendars

```
cal-com-pp-cli destination-calendars
```
— If accessed using an OAuth access token, the
```
APPS_WRITE
```
scope is required.

event-types — Manage event types

```
cal-com-pp-cli event-types create
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
```
cal-com-pp-cli event-types delete
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
```
cal-com-pp-cli event-types get
```
— Hidden event types are returned only if authentication is provided and it belongs to the event type owner. Use the...
```
cal-com-pp-cli event-types get-by-id
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
```
cal-com-pp-cli event-types update
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...

me — Manage me

```
cal-com-pp-cli me clear-my-booking-limits
```
— Removes all of the authenticated user's global booking limits. Only available to organization members — non-org...
```
cal-com-pp-cli me get
```
— If accessed using an OAuth access token, the
```
PROFILE_READ
```
scope is required.
```
cal-com-pp-cli me get-my-booking-limits
```
— Returns the authenticated user's global booking limits. Unset bounds are returned as null. Only available to...
```
cal-com-pp-cli me update
```
— Updates the authenticated user's profile. Email changes require verification and the primary email stays unchanged...
```
cal-com-pp-cli me update-my-booking-limits
```
— Partially updates the authenticated user's global booking limits. Only fields present in the request body are...
```
cal-com-pp-cli me user-ooocontroller-create-my-ooo
```
— If accessed using an OAuth access token, the
```
SCHEDULE_WRITE
```
scope is required.
```
cal-com-pp-cli me user-ooocontroller-delete-my-ooo
```
— If accessed using an OAuth access token, the
```
SCHEDULE_WRITE
```
scope is required.
```
cal-com-pp-cli me user-ooocontroller-get-my-ooo
```
— If accessed using an OAuth access token, the
```
SCHEDULE_READ
```
scope is required.
```
cal-com-pp-cli me user-ooocontroller-update-my-ooo
```
— If accessed using an OAuth access token, the
```
SCHEDULE_WRITE
```
scope is required.

notifications — Manage notifications

cal-com-pp-cli notifications subscriptions-register

— Register an app push subscription

cal-com-pp-cli notifications subscriptions-remove

— Remove an app push subscription

oauth — Manage oauth

oauth-clients — Manage oauth clients

```
cal-com-pp-cli oauth-clients create
```
— <Warning>These endpoints are deprecated and will be removed in the future.</Warning>
```
cal-com-pp-cli oauth-clients delete
```
— <Warning>These endpoints are deprecated and will be removed in the future.</Warning>
```
cal-com-pp-cli oauth-clients get
```
— <Warning>These endpoints are deprecated and will be removed in the future.</Warning>
```
cal-com-pp-cli oauth-clients get-by-id
```
— <Warning>These endpoints are deprecated and will be removed in the future.</Warning>
```
cal-com-pp-cli oauth-clients update
```
— <Warning>These endpoints are deprecated and will be removed in the future.</Warning>

organizations — Manage organizations

routing-forms — Manage routing forms

schedules — Manage schedules

```
cal-com-pp-cli schedules create
```
— Create a schedule for the authenticated user. The point of creating schedules is for event types to be available at...
```
cal-com-pp-cli schedules delete
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
```
cal-com-pp-cli schedules get
```
— Get all schedules of the authenticated user. <Note>Please make sure to pass in the cal-api-version header value as...
```
cal-com-pp-cli schedules get-default
```
— Get the default schedule of the authenticated user. <Note>Please make sure to pass in the cal-api-version header...
```
cal-com-pp-cli schedules get-scheduleid
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
```
cal-com-pp-cli schedules update
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...

selected-calendars — Manage selected calendars

```
cal-com-pp-cli selected-calendars add
```
— If accessed using an OAuth access token, the
```
APPS_WRITE
```
scope is required.
```
cal-com-pp-cli selected-calendars delete
```
— If accessed using an OAuth access token, the
```
APPS_WRITE
```
scope is required.

slots — Manage slots

```
cal-com-pp-cli slots delete-reserved
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
```
cal-com-pp-cli slots get-available
```
— There are 4 ways to get available slots for event type of an individual user: 1. By event type id. Example...
```
cal-com-pp-cli slots get-reserved
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
```
cal-com-pp-cli slots reserve
```
— Make a slot not available for others to book for a certain period of time. If you authenticate using oAuth...
```
cal-com-pp-cli slots update-reserved
```
— <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...

stripe — Manage stripe

```
cal-com-pp-cli stripe check
```
— Check Stripe connection
```
cal-com-pp-cli stripe redirect
```
— Get Stripe connect URL
```
cal-com-pp-cli stripe save
```
— Save Stripe credentials

teams — Manage teams

```
cal-com-pp-cli teams create
```
— If accessed using an OAuth access token, the
```
TEAM_PROFILE_WRITE
```
scope is required.
```
cal-com-pp-cli teams delete
```
— If accessed using an OAuth access token, the
```
TEAM_PROFILE_WRITE
```
scope is required.
```
cal-com-pp-cli teams get
```
— If accessed using an OAuth access token, the
```
TEAM_PROFILE_READ
```
scope is required.
```
cal-com-pp-cli teams get-teamid
```
— If accessed using an OAuth access token, the
```
TEAM_PROFILE_READ
```
scope is required.
```
cal-com-pp-cli teams update
```
— If accessed using an OAuth access token, the
```
TEAM_PROFILE_WRITE
```
scope is required.

verified-resources — Manage verified resources

cal-com-pp-cli verified-resources user-get-verified-email-by-id

— If accessed using an OAuth access token, the

VERIFIED_RESOURCES_READ

scope is required.

cal-com-pp-cli verified-resources user-get-verified-emails

— If accessed using an OAuth access token, the

VERIFIED_RESOURCES_READ

scope is required.

cal-com-pp-cli verified-resources user-get-verified-phone-by-id

— If accessed using an OAuth access token, the

VERIFIED_RESOURCES_READ

scope is required.

cal-com-pp-cli verified-resources user-get-verified-phone-numbers

— If accessed using an OAuth access token, the

VERIFIED_RESOURCES_READ

scope is required.

cal-com-pp-cli verified-resources user-request-email-verification-code

— Sends a verification code to the email. If accessed using an OAuth access token, the

VERIFIED_RESOURCES_WRITE

...

```
cal-com-pp-cli verified-resources user-request-phone-verification-code
```
— Sends a verification code to the phone number. If accessed using an OAuth access token, the...
```
cal-com-pp-cli verified-resources user-verify-email
```
— Use code to verify an email. If accessed using an OAuth access token, the
```
VERIFIED_RESOURCES_WRITE
```
scope is required.
```
cal-com-pp-cli verified-resources user-verify-phone-number
```
— Use code to verify a phone number. If accessed using an OAuth access token, the
```
VERIFIED_RESOURCES_WRITE
```
scope is...

webhooks — Manage webhooks

```
cal-com-pp-cli webhooks create
```
— If accessed using an OAuth access token, the
```
WEBHOOK_WRITE
```
scope is required.
```
cal-com-pp-cli webhooks delete
```
— If accessed using an OAuth access token, the
```
WEBHOOK_WRITE
```
scope is required.
```
cal-com-pp-cli webhooks get
```
— Gets a paginated list of webhooks for the authenticated user. If accessed using an OAuth access token, the...
```
cal-com-pp-cli webhooks get-webhookid
```
— If accessed using an OAuth access token, the
```
WEBHOOK_READ
```
scope is required.
```
cal-com-pp-cli webhooks update
```
— If accessed using an OAuth access token, the
```
WEBHOOK_WRITE
```
scope is required.

api-keys — 管理API密钥

```
cal-com-pp-cli api-keys
```
— 生成新的API密钥并删除当前密钥。需提供API密钥作为Authorization头中的Bearer令牌来刷新...

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头值。如果未传递...

me — 管理个人信息

```
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
```
权限。

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:

bash

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

which

resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code

means at least one match; exit code

means no confident match — fall back to

--help

or use a narrower query.

当你知道要执行的操作但不确定对应命令时，可以直接询问CLI：

bash

cal-com-pp-cli which "<用你自己的话描述功能>"

which

命令会将自然语言的功能查询解析为CLI精选功能索引中最匹配的命令。退出码

表示至少找到一个匹配项；退出码

表示没有确定的匹配项——此时可使用

--help

或更精确的查询。

Recipes

示例用法

Create a bookable link and share its URL

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

bash

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

returns the bookable URL pre-rendered (cal.com/<your-username>/<slug>);

link list

is the host's view of every link they've published.

bash

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/<your-username>/<slug>）；

link list

则是主持人查看所有已发布链接的入口。

Mark yourself out-of-office

标记自己处于休假状态

bash

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

While the OOO entry is active, Cal.com excludes the range from slot search so you don't get booked.

bash

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

休假记录生效期间，Cal.com会在时段搜索中排除该时间段，避免你被安排预订。

Today's agenda from the local store

从本地存储获取今日日程

bash

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

Returns just the four fields an agent needs from the agenda envelope — keeps context tight against deeply-nested booking payloads.

bash

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

仅返回日程信息中Agent需要的四个字段——避免处理嵌套过深的预订负载，保持上下文简洁。

Cross-event-type slot search ranked by start

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

bash

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

Fans out /v2/slots per event-type ID; returns only the earliest slot.

bash

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

会遍历每个活动类型ID调用/v2/slots接口；仅返回最早的可用时段。

No-show rate by attendee for capacity planning

按参会者统计缺席率以进行容量规划

bash

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

Local SQL aggregation over synced bookings; no API call.

bash

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

通过本地SQL聚合同步的预订数据；无需调用API。

Audit webhook coverage before adding automation

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

bash

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

Compares your registered triggers against the canonical Cal.com lifecycle set and surfaces missing subscribers.

bash

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

将已注册的触发器与Cal.com标准生命周期集合进行对比，找出遗漏的订阅者。

Reschedule a booking to the next free slot

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

bash

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

One composed command replaces three; --dry-run prints the planned move without committing.

bash

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

一个组合命令替代三个步骤；

--dry-run

会打印计划的调整内容但不会实际执行。

Auth Setup

认证设置

Cal.com uses bearer tokens prefixed with

cal_live_

(live) or

cal_test_

(test). Set

CAL_COM_TOKEN

in your environment, or run

auth set-token

once. The CLI also accepts managed-user access tokens and OAuth access tokens through the same Authorization header. Per-resource API-version pinning via

cal-api-version

is handled automatically by the client.

Run

cal-com-pp-cli doctor

to verify setup.

Cal.com使用前缀为

cal_live_

（生产环境）或

cal_test_

（测试环境）的Bearer令牌。可在环境变量中设置

CAL_COM_TOKEN

，或执行一次

auth set-token

命令。CLI也支持通过同一Authorization头使用托管用户访问令牌和OAuth访问令牌。客户端会自动处理通过

cal-api-version

实现的按资源API版本固定功能。

执行

cal-com-pp-cli doctor

验证设置是否正确。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
bash
```
cal-com-pp-cli bookings get --agent --select id,name,status
```
Previewable —
```
--dry-run
```
shows the request without sending
Offline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag

在任何命令后添加

--agent

参数，等效于：

--json --compact --no-input --no-color --yes

。

可管道化 — 标准输出为JSON，错误信息输出到标准错误
可过滤 —
```
--select
```
参数保留指定字段。点路径可深入嵌套结构；数组会遍历每个元素。对于输出冗长的API，此参数对保持上下文简洁至关重要：
bash
```
cal-com-pp-cli bookings get --agent --select id,name,status
```
可预览 —
```
--dry-run
```
显示请求内容但不发送
离线友好 — 同步/搜索命令在可用时可使用本地SQLite存储
非交互式 — 从不提示用户，所有输入均通过参数传递

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:

json

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

Parse

.results

for data and

.meta.source

to know whether it's live or local. A human-readable

N results (live)

summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.

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

json

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

解析

.results

获取数据，

.meta.source

表示数据来自生产环境还是本地存储。仅当标准输出为终端时，才会在标准错误输出中打印人类可读的

N results (live)

摘要——管道/Agent消费者仅会在标准输出中获取纯JSON。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:

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

Entries are stored locally at

~/.cal-com-pp-cli/feedback.jsonl

. They are never POSTed unless

CAL_COM_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

CAL_COM_FEEDBACK_AUTO_SEND=true

. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

当你（或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报告。简短、具体、单行描述：这类反馈的价值会不断累积。

Output Delivery

输出交付

Every command accepts

--deliver <sink>

. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename)
`webhook:<url>`	POST the output body to the URL ( `application/json` or `application/x-ndjson` when `--compact` )

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

每个命令都支持

--deliver <sink>

参数。输出会发送到指定的sink，同时（或替代）输出到标准输出，因此Agent无需手动管道即可路由命令结果。支持三种sink：

Sink	效果
`stdout`	默认值；仅输出到标准输出
`file:<path>`	原子性地将输出写入 `<path>` （先写入临时文件再重命名）
`webhook:<url>`	将输出体POST到指定URL（当使用 `--compact` 时为 `application/json` 或 `application/x-ndjson` 格式）

不支持的协议会返回结构化错误，并列出支持的类型。Webhook失败时返回非零退出码，并在标准错误输出中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

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

Explicit flags always win over profile values; profile values win over defaults.

agent-context

lists all available profiles under

available_profiles

so introspecting agents discover them at runtime.

配置文件是一组保存的参数值，可在多次调用中复用。适用于定时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在运行时发现它们。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

代码	含义
0	成功
2	使用错误（参数错误）
3	资源未找到
4	需要认证
5	API错误（上游问题）
7	速率限制（请等待后重试）
10	配置错误

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
cal-com-pp-cli --help
```
output
Starts with
install
→ ends with
```
mcp
```
→ MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with
```
--agent
```
)

解析

$ARGUMENTS

的规则：

为空、
help
或
--help
→ 显示
```
cal-com-pp-cli --help
```
输出
以
install
开头 → 若以
```
mcp
```
结尾 → MCP安装；否则 → 参见顶部的前提条件
其他情况 → 直接使用（添加
```
--agent
```
参数执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP server:

bash

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

bash

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

Verify:
```
claude mcp list
```

安装MCP服务器：

bash

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

注册到Claude Code：

bash

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

验证：
```
claude mcp list
```

Direct Use

直接使用

Check if installed:
```
which cal-com-pp-cli
```
If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the

--agent

flag:

bash

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

If ambiguous, drill into subcommand help:
```
cal-com-pp-cli <command> --help
```
.

检查是否已安装：
```
which cal-com-pp-cli
```
如果未找到，提供安装选项（参见顶部的前提条件）。
将用户查询与上述独特功能和命令参考中的最佳命令匹配。

添加

--agent

参数执行：

bash

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

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