Back to Details

calcom-access

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cal.com Access

Cal.com 访问

Manage Cal.com bookings and event types programmatically via Claude Code CLI.
通过Claude Code CLI以编程方式管理Cal.com的预订和活动类型。

MANDATORY PREFLIGHT (Execute Before Any Cal.com Operation)

必选预检步骤（执行任何Cal.com操作前完成）

CRITICAL: You MUST complete this preflight checklist before running any Cal.com commands. Do NOT skip steps.
重要提示：在运行任何Cal.com命令之前，你必须完成此预检清单。请勿跳过步骤。

Step 1: Check CLI Binary Exists

步骤1：检查CLI二进制文件是否存在

bash
ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom" 2>/dev/null || echo "BINARY_NOT_FOUND"
If BINARY_NOT_FOUND: Build it first:
bash
cd ~/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli && bun install && bun run build
bash
ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom" 2>/dev/null || echo "BINARY_NOT_FOUND"
如果返回BINARY_NOT_FOUND：请先构建它：
bash
cd ~/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli && bun install && bun run build

Step 2: Check CALCOM_OP_UUID Environment Variable

步骤2：检查CALCOM_OP_UUID环境变量

bash
echo "CALCOM_OP_UUID: ${CALCOM_OP_UUID:-NOT_SET}"
If NOT_SET: You MUST run the Setup Flow below. Do NOT proceed to Cal.com commands.
bash
echo "CALCOM_OP_UUID: ${CALCOM_OP_UUID:-NOT_SET}"
如果返回NOT_SET：你必须运行下方的设置流程。请勿继续执行Cal.com命令。

Step 3: Verify 1Password Authentication

步骤3：验证1Password身份验证

bash
op account list 2>&1 | head -3
If error or not signed in: Inform user to run 
op signin
first.
bash
op account list 2>&1 | head -3
如果出现错误或未登录：告知用户先运行
op signin
命令。

Step 4: Test API Connectivity

步骤4：测试API连通性

bash
CALCOM_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom"
$CALCOM_CLI event-types list 2>&1 | head -5
bash
CALCOM_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom"
$CALCOM_CLI event-types list 2>&1 | head -5

Setup Flow (When CALCOM_OP_UUID is NOT_SET)

设置流程（当CALCOM_OP_UUID为NOT_SET时）

Follow these steps IN ORDER. Use AskUserQuestion at decision points.
按顺序执行以下步骤。在决策点使用AskUserQuestion交互。

Setup Step 1: Check 1Password CLI

设置步骤1：检查1Password CLI

bash
command -v op && echo "OP_CLI_INSTALLED" || echo "OP_CLI_MISSING"
If OP_CLI_MISSING: Stop and inform user:
1Password CLI is required. Install with: 
brew install 1password-cli
bash
command -v op && echo "OP_CLI_INSTALLED" || echo "OP_CLI_MISSING"
如果返回OP_CLI_MISSING：停止操作并告知用户：
需要安装1Password CLI。安装命令：
brew install 1password-cli

Setup Step 2: Discover Cal.com API Keys in 1Password

设置步骤2：在1Password中查找Cal.com API密钥

bash
op item list --vault "Claude Automation" --format json 2>/dev/null | jq -r '.[] | select(.title | test("calcom|cal.com|calendar"; "i")) | "\(.id)\t\(.title)"'
Parse the output and proceed based on results.
bash
op item list --vault "Claude Automation" --format json 2>/dev/null | jq -r '.[] | select(.title | test("calcom|cal.com|calendar"; "i")) | "\(.id)\t\(.title)"'
解析输出结果并根据结果继续操作。

Setup Step 3: User Selects API Credentials

设置步骤3：用户选择API凭据

If items found, use AskUserQuestion with discovered items.
If NO items found, guide the user:
  1. Log into the Cal.com instance (self-hosted or cal.com)
  2. Go to Settings > Developer > API Keys
  3. Generate a new API key with appropriate scopes
  4. Store in 1Password Claude Automation vault:
bash
op item create --category "API Credential" --title "Cal.com API Key" \
  --vault "Claude Automation" \
  "credential=<api-key>" \
  "api_url=<cal.com-instance-url>"
如果找到相关条目，使用AskUserQuestion让用户从发现的条目中选择。
如果未找到任何条目，引导用户执行以下操作：
  1. 登录Cal.com实例（自托管或官方cal.com）
  2. 进入 设置 > 开发者 > API密钥
  3. 生成一个具有适当权限的新API密钥
  4. 将其存储到1Password的Claude Automation保险箱中：
bash
op item create --category "API Credential" --title "Cal.com API Key" \
  --vault "Claude Automation" \
  "credential=<api-key>" \
  "api_url=<cal.com-instance-url>"

Setup Step 4: Configure mise

设置步骤4：配置mise

After user selects an item (with UUID), use AskUserQuestion to confirm adding to 
.mise.local.toml
:
toml
[env]
CALCOM_OP_UUID = "<selected-uuid>"
用户选择条目（获取UUID后），使用AskUserQuestion确认是否将以下内容添加到
.mise.local.toml
：
toml
[env]
CALCOM_OP_UUID = "<selected-uuid>"

Setup Step 5: Reload and Verify

设置步骤5：重新加载并验证

bash
mise trust 2>/dev/null || true
cd . && echo "CALCOM_OP_UUID after reload: ${CALCOM_OP_UUID:-NOT_SET}"
bash
mise trust 2>/dev/null || true
cd . && echo "重新加载后的CALCOM_OP_UUID: ${CALCOM_OP_UUID:-NOT_SET}"

Setup Step 6: Test Connection

设置步骤6：测试连接

bash
CALCOM_OP_UUID="${CALCOM_OP_UUID}" $HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom event-types list
bash
CALCOM_OP_UUID="${CALCOM_OP_UUID}" $HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom event-types list

Cal.com Commands (Only After Preflight Passes)

Cal.com 命令（仅在预检通过后执行）

bash
CALCOM_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom"
bash
CALCOM_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom"

List event types

列出活动类型

$CALCOM_CLI event-types list
$CALCOM_CLI event-types list

List bookings

列出预订记录

$CALCOM_CLI bookings list -n 10
$CALCOM_CLI bookings list -n 10

List bookings by status

按状态列出预订记录

$CALCOM_CLI bookings list --status upcoming -n 20
$CALCOM_CLI bookings list --status upcoming -n 20

Get booking details

获取预订详情

$CALCOM_CLI bookings get <booking_id>
$CALCOM_CLI bookings get <booking_id>

Create event type

创建活动类型

$CALCOM_CLI event-types create --title "30min Interview" --slug "interview-30" --length 30
$CALCOM_CLI event-types create --title "30min Interview" --slug "interview-30" --length 30

Update event type

更新活动类型

$CALCOM_CLI event-types update <event_type_id> --title "Updated Title"
$CALCOM_CLI event-types update <event_type_id> --title "Updated Title"

List schedules (availability)

列出日程（可用时间）

$CALCOM_CLI schedules list
$CALCOM_CLI schedules list

JSON output (for parsing)

JSON格式输出（用于解析）

$CALCOM_CLI bookings list -n 10 --json
undefined
$CALCOM_CLI bookings list -n 10 --json
undefined

Cal.com API v2 Reference

Cal.com API v2 参考

EndpointCLI CommandDescription
Event Types
event-types list
List all event types
Event Types
event-types create
Create new event type
Bookings
bookings list
List bookings
Bookings
bookings get
Get booking details
Bookings
bookings cancel
Cancel a booking
Schedules
schedules list
List availability windows
Schedules
schedules create
Create availability
Availability
availability check
Check slot availability
端点CLI 命令描述
Event Types
event-types list
列出所有活动类型
Event Types
event-types create
创建新的活动类型
Bookings
bookings list
列出预订记录
Bookings
bookings get
获取预订详情
Bookings
bookings cancel
取消预订
Schedules
schedules list
列出可用时间窗口
Schedules
schedules create
创建可用时间
Availability
availability check
检查时段可用性

Environment Variables

环境变量

VariableRequiredDescription
CALCOM_OP_UUID
Yes1Password item UUID for API key
CALCOM_API_URL
NoAPI base URL (default: self-hosted)
变量名是否必填描述
CALCOM_OP_UUID
是存储API密钥的1Password条目UUID
CALCOM_API_URL
否API基础URL（默认：自托管实例）

References

参考文档

  • calcom-api-setup.md - Cal.com API key setup guide
  • mise-setup.md - Step-by-step mise configuration
  • calcom-api-setup.md - Cal.com API密钥设置指南
  • mise-setup.md - mise配置分步指南

Post-Change Checklist

变更后检查清单

  • YAML frontmatter valid (no colons in description)
  • Trigger keywords current
  • Path patterns use $HOME not hardcoded paths
  • References exist and are linked
  • YAML前置元数据有效（描述中无冒号）
  • 触发关键词为最新版本
  • 路径模式使用$HOME而非硬编码路径
  • 参考文档存在且链接有效