Apple Calendar CLI (accli)

安装

npm install -g @joargp/accli

系统要求：仅限 macOS（使用 JavaScript for Automation）

概述

accli 工具提供对 macOS Apple Calendar 的命令行访问。它支持列出日历、查询事件、创建/更新/删除事件以及跨日历检查可用性。

快速参考

日期时间格式

• 定时事件：YYYY-MM-DDTHH:mm 或 YYYY-MM-DDTHH:mm:ss
• 全天事件：YYYY-MM-DD

全局选项

• --json - 输出为 JSON 格式（建议用于解析）
• --help - 显示任何命令的帮助信息

命令

列出日历

accli calendars [--json]

列出所有可用日历的名称和持久 ID。首先运行此命令以发现可用日历及其 ID。

列出事件

accli events <calendarName> [options]

选项：

• --calendar-id<id>- 持久性日历ID（推荐使用，优于名称）
• --from<日期时间>- 范围起始时间（默认：当前时间）
• --to<日期时间>- 范围结束时间（默认：起始时间 + 7天）
• --max<n>- 返回事件的最大数量（默认：50）
• --query<q>- 对摘要/地点/描述进行不区分大小写的筛选
• --json - 输出JSON格式

示例：

# Events from Work calendar for this week
accli events Work --json

# Events in January
accli events Work --from 2025-01-01 --to 2025-01-31 --json

# Search for specific events
accli events Work --query "standup" --max 10 --json

获取单个事件

accli event <calendarName> <eventId> [--json]

通过事件ID检索特定事件的详细信息。

创建事件

accli create <calendarName> --summary <s> --start <datetime> --end <datetime> [options]

必需选项：

• --summary<s>- 事件标题
• --start<日期时间>- 开始时间
• --结束<日期时间>- 结束时间

可选：

• --地点<l>- 事件地点
• --描述<d>- 事件描述
• --全天 - 创建一个全天事件
• --json - 输出JSON格式

示例：

# Create a timed meeting
accli create Work --summary "Team Standup" --start 2025-01-15T09:00 --end 2025-01-15T09:30 --json

# Create an all-day event
accli create Personal --summary "Vacation" --start 2025-07-01 --end 2025-07-05 --all-day --json

# Create with location and description
accli create Work --summary "Client Meeting" --start 2025-01-15T14:00 --end 2025-01-15T15:00 \
  --location "Conference Room A" --description "Q1 planning discussion" --json

更新事件

accli update <calendarName> <eventId> [options]

选项（均为可选 - 仅提供需要更改的内容）：

• --摘要<s>- 新标题
• --开始<日期时间>- 新的开始时间
• --结束<日期时间>- 新的结束时间
• --地点<l>- 新地点
• --description<d>- 新描述
• --all-day - 转换为全天事件
• --no-all-day - 转换为定时事件
• --json - 输出JSON

示例：

accli update Work event-id-123 --summary "Updated Meeting Title" --start 2025-01-15T15:00 --end 2025-01-15T16:00 --json

删除事件

accli delete <calendarName> <eventId> [--json]

永久删除一个事件。执行前需与用户确认。

检查空闲/忙碌状态

accli freebusy --calendar <name> --from <datetime> --to <datetime> [options]

选项：

• --calendar<名称>- 日历名称（可重复指定多个日历）
• --calendar-id<ID>- 持久日历ID（可重复）
• --from<日期时间>- 范围开始时间（必需）
• --to<日期时间>- 范围结束时间（必填）
• --json - 输出 JSON 格式

显示繁忙时间段，排除已取消、已拒绝和透明事件。

示例：

# Check availability across calendars
accli freebusy --calendar Work --calendar Personal --from 2025-01-15 --to 2025-01-16 --json

# Check specific hours
accli freebusy --calendar Work --from 2025-01-15T09:00 --to 2025-01-15T18:00 --json

配置

# Set default calendar (interactive)
accli config set-default

# Set default by name
accli config set-default --calendar Work

# Show current config
accli config show

# Clear default
accli config clear

当设置了默认日历时，如果未指定日历，命令将自动使用该日历。

工作流指南

创建事件前

1. 列出日历以获取可用的日历名称/ID
2. 检查空闲/繁忙状态以查找可用时间段
3. 创建前与用户确认事件详情

最佳实践

• 始终使用 --json 标志以便程序化解析
• 为提高可靠性，优先使用 --calendar-id 而非日历名称
• 查询事件时，从合理的日期范围开始
• 执行删除操作前与用户确认
• 始终使用 ISO 8601 日期时间格式

常见模式

查找空闲时间段并安排：

# 1. Check availability
accli freebusy --calendar Work --from 2025-01-15T09:00 --to 2025-01-15T18:00 --json

# 2. Create event in available slot
accli create Work --summary "Meeting" --start 2025-01-15T14:00 --end 2025-01-15T15:00 --json

查看今日日程：

accli events Work --from $(date +%Y-%m-%d) --to $(date -v+1d +%Y-%m-%d) --json