CalDAV Sync Tool

Manage calendar events and todos via CalDAV protocol. Supports Google Calendar, iCloud, Nextcloud, Fastmail, NetEase (163/126/yeah.net), and any standard CalDAV server.

Configuration

Run the setup script to install dependencies and configure your CalDAV account:

bash setup.sh

If running commands manually without setup.sh, install dependencies first:

npm install --production

Configuration is stored at ~/.config/mail-skills/.env (shared with imap-smtp-email skill). If no shared config is found, the skill falls back to a .env file in the skill directory.

Config file format

# Default account
PROVIDER=163
[email protected]
PASSWORD=your_password
CALDAV_DEFAULT_CALENDAR=

The PROVIDER preset auto-fills the CalDAV server URL. For custom servers:

PROVIDER=custom
[email protected]
PASSWORD=your_password
CALDAV_SERVER_URL=https://your-caldav-server.com/

Multi-Account

You can configure additional accounts in the same config file. Each account uses a name prefix (uppercase) on all variables.

# Work account (WORK_ prefix)
WORK_PROVIDER=gmail
[email protected]
WORK_PASSWORD=app_password
WORK_CALDAV_DEFAULT_CALENDAR=work

Add --account \x3Cname> before the command:

node scripts/caldav.js --account work list-calendars
node scripts/caldav.js --account work list-events --start 2026-01-01 --end 2026-12-31

Supported Providers

Commands

list-calendars

List all available calendars.

node scripts/caldav.js [--account \x3Cname>] list-calendars

list-events

Query events in a time range.

node scripts/caldav.js [--account \x3Cname>] list-events --start \x3Cdate> --end \x3Cdate> [--calendar \x3Cid>]

get-event

Get a specific event by UID.

node scripts/caldav.js [--account \x3Cname>] get-event --uid \x3Cuid> [--calendar \x3Cid>]

create-event

Create a new calendar event.

node scripts/caldav.js [--account \x3Cname>] create-event --summary \x3Ctext> --start \x3Cdatetime> --end \x3Cdatetime> \
  [--description \x3Ctext>] [--location \x3Ctext>] [--calendar \x3Cid>]

update-event

Update an existing event.

node scripts/caldav.js [--account \x3Cname>] update-event --uid \x3Cuid> [--summary \x3Ctext>] [--start \x3Cdatetime>] \
  [--end \x3Cdatetime>] [--description \x3Ctext>] [--location \x3Ctext>] [--calendar \x3Cid>]

delete-event

Delete an event.

node scripts/caldav.js [--account \x3Cname>] delete-event --uid \x3Cuid> [--calendar \x3Cid>]

list-todos

List all todos/tasks.

node scripts/caldav.js [--account \x3Cname>] list-todos [--status \x3Call|pending|completed>] [--calendar \x3Cid>]

create-todo

Create a new todo/task.

node scripts/caldav.js [--account \x3Cname>] create-todo --summary \x3Ctext> [--due \x3Cdate>] \
  [--description \x3Ctext>] [--priority \x3C1-9>] [--calendar \x3Cid>]

update-todo

Update an existing todo.

node scripts/caldav.js [--account \x3Cname>] update-todo --uid \x3Cuid> [--summary \x3Ctext>] [--due \x3Cdate>] \
  [--status \x3Cpending|completed>] [--calendar \x3Cid>]

delete-todo

Delete a todo.

node scripts/caldav.js [--account \x3Cname>] delete-todo --uid \x3Cuid> [--calendar \x3Cid>]

freebusy

Query free/busy information for a time range.

node scripts/caldav.js [--account \x3Cname>] freebusy --start \x3Cdatetime> --end \x3Cdatetime> [--calendar \x3Cid>]

list-accounts

List all configured CalDAV accounts.

node scripts/caldav.js list-accounts

Security Notes

• Configuration is stored at ~/.config/mail-skills/.env with 600 permissions (owner read/write only)
• For Google: regular password is rejected -- generate an App Password at https://myaccount.google.com/apppasswords
• For NetEase: use authorization code (授权码), not account password

Troubleshooting

Connection failed:

• Verify server URL is correct and accessible
• Check username and password

Authentication failed:

• For Google: use App Password, not regular password
• For NetEase: use authorization code, not account password
• For iCloud: use App-Specific Password

No calendars found:

• Verify CalDAV service is enabled in your account settings
• Check the server URL includes the correct path

Related Skills

• imap-smtp-email - Read, search, manage, and send emails via IMAP/SMTP. Supports Gmail, Outlook, NetEase (163/126/188), and any standard IMAP/SMTP server. Install with:

  npx skills add https://github.com/gzlicanyi/mail-skills -s imap-smtp-email
  

Feedback

Issues and pull requests are welcome at github.com/gzlicanyi/mail-skills.