caldav-cli
A CalDAV CLI client. Manages multiple accounts with secure OS keychain storage. Supports iCloud, Google (OAuth2), Yandex and any custom CalDAV server.
Installation
Requires Node.js >= 18.
CODEBLOCK0
After installation the caldav-cli command is available globally.
Quick Start
CODEBLOCK1
Account Management
Add account (interactive wizard — prompts for provider, credentials, tests connection):
CODEBLOCK2
List configured accounts:
CODEBLOCK3
Remove an account:
CODEBLOCK4
View Events
CODEBLOCK5
JSON output (for scripting):
CODEBLOCK6
Create Events
Interactive wizard (prompts for all fields):
CODEBLOCK7
Non-interactive (all options via flags):
CODEBLOCK8
Partial flags (wizard prompts for the rest):
CODEBLOCK9
JSON output after creation:
CODEBLOCK10
Supported Providers
| Provider | Auth | Server URL |
|---|
| Apple iCloud | Basic (app-specific password) | INLINECODE1 |
| Google Calendar |
OAuth2 (Client ID + Secret) |
https://apidata.googleusercontent.com/caldav/v2 |
| Yandex Calendar | Basic (app password) |
https://caldav.yandex.ru |
| Custom | Basic | User provides URL |
Google Calendar Setup
Google requires OAuth2. Before running caldav-cli account add:
- 1. Go to https://console.cloud.google.com/
- Create a project, enable CalDAV API
- Create OAuth client ID (Desktop app type)
- Note the Client ID and Client Secret
The wizard will ask for these, then open a browser for authorization. The refresh token is stored securely in the OS keychain.
Data Storage
- - Passwords, OAuth2 refresh tokens, and OAuth2 client credentials (Client ID, Client Secret, Token URL): OS keychain (macOS Keychain, Linux libsecret, Windows Credential Vault) via
@napi-rs/keyring. Never written to disk in plaintext. - Account metadata (name, provider ID, username, server URL):
~/.config/caldav-cli/config.json (file permissions 0600).
No secrets are stored on disk. Existing installations that stored OAuth2 client credentials in config.json are automatically migrated to the keychain on first run.
Flag Reference
events list
| Flag | Short | Description | Default |
|---|
| INLINECODE10 | INLINECODE11 | Account name | default account |
| INLINECODE12 |
| Start date (YYYY-MM-DD) | today |
|
--to <date> | | End date (YYYY-MM-DD) | today + 7 days |
|
--calendar <name> |
-c | Filter by calendar name | all calendars |
|
--json | | Output as JSON | false |
events create
| Flag | Short | Description |
|---|
| INLINECODE18 | INLINECODE19 | Event title |
| INLINECODE20 |
-s | Start (YYYY-MM-DDTHH:mm) |
|
--end <datetime> |
-e | End (YYYY-MM-DDTHH:mm) |
|
--account <name> |
-a | Account name |
|
--calendar <name> |
-c | Calendar name |
|
--description <text> |
-d | Event description |
|
--location <text> |
-l | Event location |
|
--json | | Output as JSON |
All events create flags are optional. Omitted values trigger interactive prompts.
caldav-cli
一个CalDAV CLI客户端。支持多账户管理，使用安全的操作系统密钥链存储。支持iCloud、Google（OAuth2）、Yandex以及任何自定义CalDAV服务器。
安装
需要Node.js >= 18。
bash
npm install -g caldav-cli
安装后，caldav-cli命令即可全局使用。
快速开始
bash
caldav-cli account add # 交互式向导：选择提供商，输入凭据
caldav-cli events list # 显示未来7天的事件
caldav-cli events create # 交互式向导：创建新事件
账户管理
添加账户（交互式向导 — 提示输入提供商、凭据，测试连接）：
bash
caldav-cli account add
列出已配置的账户：
bash
caldav-cli account list
删除账户：
bash
caldav-cli account remove <名称>
查看事件
bash
caldav-cli events list # 未来7天（默认）
caldav-cli events list --from 2026-02-10 --to 2026-02-20
caldav-cli events list -a work # 指定账户
caldav-cli events list -c 团队日历 # 按日历名称筛选
caldav-cli events list -a work -c 个人 --from 2026-03-01 --to 2026-03-31
JSON输出（适用于脚本）：
bash
caldav-cli events list --json
caldav-cli events list --json --from 2026-02-10 --to 2026-02-20
创建事件
交互式向导（提示输入所有字段）：
bash
caldav-cli events create
非交互式（所有选项通过标志指定）：
bash
caldav-cli events create \
--title 团队站会 \
--start 2026-02-10T10:00 \
--end 2026-02-10T10:30 \
--account work \
--calendar 团队日历 \
--description 每日同步 \
--location 42号会议室
部分标志（其余字段由向导提示）：
bash
caldav-cli events create --title 午餐 --account work
创建后的JSON输出：
bash
caldav-cli events create --json --title 活动 --start 2026-02-10T10:00 --end 2026-02-10T11:00
支持的提供商
| 提供商 | 认证方式 | 服务器URL |
|---|
| Apple iCloud | 基本认证（应用专用密码） | https://caldav.icloud.com |
| Google日历 |
OAuth2（客户端ID + 密钥） | https://apidata.googleusercontent.com/caldav/v2 |
| Yandex日历 | 基本认证（应用密码） | https://caldav.yandex.ru |
| 自定义 | 基本认证 | 用户提供URL |
Google日历设置
Google需要OAuth2认证。在运行caldav-cli account add之前：
- 1. 访问 https://console.cloud.google.com/
- 创建项目，启用CalDAV API
- 创建OAuth客户端ID（桌面应用类型）
- 记录客户端ID和客户端密钥
向导会要求输入这些信息，然后打开浏览器进行授权。刷新令牌会安全存储在操作系统密钥链中。
数据存储
- - 密码、OAuth2刷新令牌和OAuth2客户端凭据（客户端ID、客户端密钥、令牌URL）：通过@napi-rs/keyring存储在操作系统密钥链中（macOS密钥链、Linux libsecret、Windows凭据保险库）。永远不会以明文形式写入磁盘。
- 账户元数据（名称、提供商ID、用户名、服务器URL）：~/.config/caldav-cli/config.json（文件权限0600）。
没有秘密信息存储在磁盘上。已安装的旧版本如果曾在config.json中存储OAuth2客户端凭据，首次运行时会自动迁移到密钥链。
标志参考
events list
| 标志 | 缩写 | 描述 | 默认值 |
|---|
| --account <名称> | -a | 账户名称 | 默认账户 |
| --from <日期> |
| 开始日期（YYYY-MM-DD） | 今天 |
| --to <日期> | | 结束日期（YYYY-MM-DD） | 今天 + 7天 |
| --calendar <名称> | -c | 按日历名称筛选 | 所有日历 |
| --json | | 输出为JSON | false |
events create
| 标志 | 缩写 | 描述 |
|---|
| --title <标题> | -t | 事件标题 |
| --start <日期时间> |
-s | 开始时间（YYYY-MM-DDTHH:mm） |
| --end <日期时间> | -e | 结束时间（YYYY-MM-DDTHH:mm） |
| --account <名称> | -a | 账户名称 |
| --calendar <名称> | -c | 日历名称 |
| --description <文本> | -d | 事件描述 |
| --location <文本> | -l | 事件地点 |
| --json | | 输出为JSON |
所有events create的标志都是可选的。省略的值会触发交互式提示。
