介绍
# Apple Calendar CLI (accli)
## 安装
```bash npm install -g @joargp/accli ```
**要求：** 仅限 macOS（使用 JavaScript for Automation）
## 概述
accli 工具提供对 macOS Apple 日历的命令行访问。它支持列出日历、查询事件、创建/更新/删除事件，以及检查跨日历的空闲状态。
## 快速参考
### 日期时间格式 - 定时事件：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 <datetime> - 范围的开始时间（默认：现在） - --to <datetime> - 范围的结束时间（默认：from + 7 天） - --max <n> - 返回的最大事件数（默认：50） - --query <q> - 对摘要/位置/描述进行不区分大小写的过滤 - --json - 输出 JSON
示例：
```bash # 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 <datetime> - 开始时间 - --end <datetime> - 结束时间
可选： - --location <l> - 事件地点 - --description <d> - 事件描述 - --all-day - 创建全天事件 - --json - 输出 JSON
示例：
```bash # 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] ```
选项（均为可选 - 仅提供需要更改的内容）： - --summary <s> - 新标题 - --start <datetime> - 新开始时间 - --end <datetime> - 新结束时间 - --location <l> - 新地点 - --description <d> - 新描述 - --all-day - 转换为全天事件 - --no-all-day - 转换为定时事件 - --json - 输出 JSON
示例：
```bash 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 <name> - 日历名称（可重复以指定多个日历） - --calendar-id <id> - 持久化日历 ID（可重复） - --from <datetime> - 范围的开始时间（必需） - --to <datetime> - 范围的结束时间（必需） - --json - 输出 JSON
显示忙碌时间段，不包括已取消、已拒绝和透明的事件。
示例：
```bash # 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 ```
### 配置
```bash # 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 日期时间格式
### 常用模式
查找空闲时段并安排日程：
```bash # 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 ```
查看今天的日程：
```bash accli events Work --from $(date +%Y-%m-%d) --to $(date -v+1d +%Y-%m-%d) --json ```