accli — Apple Calendar CLI

accli 通过 EventKit 在 macOS 上管理 Apple 日历。所有命令均支持 --json 参数以输出结构化数据。退出码含义如下：0=成功，1=运行时错误，2=校验错误，10=授权错误。

首次运行：执行 accli setup 以授予日历访问权限（需在“系统设置”>“隐私与安全性”>“日历”中启用“完全访问”）。

日历列表

accli calendars [--json]

返回日历列表，包含字段：id、name、source、index、writable。始终优先使用 --calendar-id 而非日历名称——ID 是稳定的，而名称可能被重命名。

事件列表

accli events [] [--calendar-id ] --from  --to  [--json]

列出指定日期范围内的事件。必须指定日历（可使用日历名称、--calendar-id，或通过 accli config set-default 设置默认日历）。

单个事件详情

accli event []  [--calendar-id ] [--json]

获取完整事件信息，包括 alerts 数组（单位为事件开始前的分钟数）。

创建事件

accli create  --summary  --start  --end  
  [--location ] [--description ] [--all-day] 
  [--alert ] [--alert ] 
  [--recur daily|weekly|monthly|yearly] [--recur-count ] [--recur-end ] 
  [--json]

• --alert 可重复使用——每出现一次即添加一个提醒（单位为事件开始前的分钟数）
• --recur-end 与 --recur-count 互斥，不可同时指定
• 全天事件：对 --start 和 --end 使用 YYYY-MM-DD 格式
• 定时事件：对 --start 和 --end 使用 YYYY-MM-DDTHH:mm 格式

更新事件

accli update   
  [--summary ] [--start ] [--end ] 
  [--location ] [--description ] 
  [--alert ] [--alert ] 
  [--dry-run] [--json]

--alert 在更新时将**替换全部已有提醒**；若省略该参数，则保持原有提醒不变。
--dry-run 不执行任何修改，仅返回 { dryRun: true, wouldUpdate: { eventId, changes } }。

删除事件

accli delete   [--dry-run] [--json]

--dry-run 不执行删除操作，仅返回 { dryRun: true, wouldDelete: { id, summary, calendar, start, end } }。

搜索事件

accli search --query  [--from ] [--to ] [--calendar-id ] [--json]

不区分大小写地在事件标题（summary）、地点（location）和描述（description）中进行全文搜索。若未指定 --calendar-id，则搜索所有日历。返回结果中每个事件均包含 calendarId 字段，便于精准定位。

导出事件

accli export --from  --to  [--calendar-id ] [--json]

按日历分组导出全部事件。响应格式为：{ calendars: [{ id, name, source, events, truncated }], totalEvents, truncated }。每个日历最多导出 500 个事件；若达到上限，则对应日历的 truncated 字段设为 true。

空闲/忙碌时段查询（Free/Busy）

accli freebusy --from  --to  [--calendar-name ] [--json]

返回所有日历中的忙碌时间段。

配置管理

accli config set-default --calendar-id  [--json]
accli config show [--json]
accli config clear [--json]

默认日历配置持久化至 ~/.acclirc（可通过环境变量 ACCLI_CONFIG_PATH 覆盖路径）。当命令需要指定日历时，若未显式提供日历参数，则自动使用默认日历。

日期时间格式说明

• 定时事件格式：YYYY-MM-DDTHH:mm 或 YYYY-MM-DDTHH:mm:ss
• 仅日期格式（适用于全天事件、--from/--to 参数）：YYYY-MM-DD

自动化代理（Agent）最佳实践

• 程序化解析时，始终使用 --json
• 始终使用 --calendar-id 而非日历名称（确保跨重命名操作稳定性）
• 执行破坏性操作（如更新、删除）前，务必先使用 --dry-run 确认目标事件
• 执行更新或删除前，建议先用 accli search 查找对应 eventId
• 处理 JSON 响应前，请检查 ok: false 字段以判断是否出错
• accli export 适用于完整日历备份；请检查响应中的 truncated 字段确认是否截断
• 添加多个提醒：重复使用 --alert 参数，例如：--alert 5 --alert 15
• 仅支持 macOS（darwin 系统），切勿在非 darwin 系统上运行

错误码说明