Back to Details

caldav-calendar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CalDAV Calendar (vdirsyncer + khal)

CalDAV Calendar (vdirsyncer + khal)

vdirsyncer syncs CalDAV calendars to local 
.ics
files. khal reads and writes them.
vdirsyncer 可将CalDAV日历同步至本地
.ics
文件，khal 负责对这些文件进行读写操作。

Sync First

先同步

Always sync before querying or after making changes:
bash
vdirsyncer sync
在查询日历或修改内容后，务必先执行同步：
bash
vdirsyncer sync

View Events

查看事件

bash
khal list                        # Today
khal list today 7d               # Next 7 days
khal list tomorrow               # Tomorrow
khal list 2026-01-15 2026-01-20  # Date range
khal list -a Work today          # Specific calendar
bash
khal list                        # 查看今日事件
khal list today 7d               # 查看未来7天事件
khal list tomorrow               # 查看明日事件
khal list 2026-01-15 2026-01-20  # 查看指定日期范围的事件
khal list -a Work today          # 查看指定日历（Work）的今日事件

Search

搜索事件

bash
khal search "meeting"
khal search "dentist" --format "{start-date} {title}"
bash
khal search "meeting"
khal search "dentist" --format "{start-date} {title}"

Create Events

创建事件

bash
khal new 2026-01-15 10:00 11:00 "Meeting title"
khal new 2026-01-15 "All day event"
khal new tomorrow 14:00 15:30 "Call" -a Work
khal new 2026-01-15 10:00 11:00 "With notes" :: Description goes here
After creating, sync to push changes:
bash
vdirsyncer sync
bash
khal new 2026-01-15 10:00 11:00 "Meeting title"
khal new 2026-01-15 "All day event"
khal new tomorrow 14:00 15:30 "Call" -a Work
khal new 2026-01-15 10:00 11:00 "With notes" :: Description goes here
创建完成后，执行同步以推送修改：
bash
vdirsyncer sync

Edit Events (interactive)

编辑事件（交互式）

khal edit
is interactive — requires a TTY. Use tmux if automating:
bash
khal edit "search term"
khal edit -a CalendarName "search term"
khal edit --show-past "old event"
Menu options:
  • s
    → edit summary
  • d
    → edit description
  • t
    → edit datetime range
  • l
    → edit location
  • D
    → delete event
  • n
    → skip (save changes, next match)
  • q
    → quit
After editing, sync:
bash
vdirsyncer sync
khal edit
为交互式操作，需要TTY环境。若要自动化执行，可使用tmux：
bash
khal edit "search term"
khal edit -a CalendarName "search term"
khal edit --show-past "old event"
菜单选项：
  • s
    → 编辑标题
  • d
    → 编辑描述
  • t
    → 编辑时间范围
  • l
    → 编辑地点
  • D
    → 删除事件
  • n
    → 跳过（保存修改，查看下一个匹配项）
  • q
    → 退出
编辑完成后，执行同步：
bash
vdirsyncer sync

Delete Events

删除事件

Use 
khal edit
, then press 
D
to delete.
使用 
khal edit
找到目标事件后，按 
D
即可删除。

Output Formats

输出格式

For scripting:
bash
khal list --format "{start-date} {start-time}-{end-time} {title}" today 7d
khal list --format "{uid} | {title} | {calendar}" today
Placeholders: 
{title}
, 
{description}
, 
{start}
, 
{end}
, 
{start-date}
, 
{start-time}
, 
{end-date}
, 
{end-time}
, 
{location}
, 
{calendar}
, 
{uid}
用于脚本编写的格式示例：
bash
khal list --format "{start-date} {start-time}-{end-time} {title}" today 7d
khal list --format "{uid} | {title} | {calendar}" today
可用占位符：
{title}
, 
{description}
, 
{start}
, 
{end}
, 
{start-date}
, 
{start-time}
, 
{end-date}
, 
{end-time}
, 
{location}
, 
{calendar}
, 
{uid}

Caching

缓存

khal caches events in 
~/.local/share/khal/khal.db
. If data looks stale after syncing:
bash
rm ~/.local/share/khal/khal.db
khal 会将事件缓存至 
~/.local/share/khal/khal.db
。若同步后数据仍显示过时，可执行：
bash
rm ~/.local/share/khal/khal.db

Initial Setup

初始配置

1. Configure vdirsyncer (
~/.config/vdirsyncer/config
)

1. 配置vdirsyncer（
~/.config/vdirsyncer/config
）

Example for iCloud:
ini
[general]
status_path = "~/.local/share/vdirsyncer/status/"

[pair icloud_calendar]
a = "icloud_remote"
b = "icloud_local"
collections = ["from a", "from b"]
conflict_resolution = "a wins"

[storage icloud_remote]
type = "caldav"
url = "https://caldav.icloud.com/"
username = "your@icloud.com"
password.fetch = ["command", "cat", "~/.config/vdirsyncer/icloud_password"]

[storage icloud_local]
type = "filesystem"
path = "~/.local/share/vdirsyncer/calendars/"
fileext = ".ics"
Provider URLs:
  • iCloud: 
    https://caldav.icloud.com/
  • Google: Use 
    google_calendar
    storage type
  • Fastmail: 
    https://caldav.fastmail.com/dav/calendars/user/EMAIL/
  • Nextcloud: 
    https://YOUR.CLOUD/remote.php/dav/calendars/USERNAME/
iCloud配置示例：
ini
[general]
status_path = "~/.local/share/vdirsyncer/status/"

[pair icloud_calendar]
a = "icloud_remote"
b = "icloud_local"
collections = ["from a", "from b"]
conflict_resolution = "a wins"

[storage icloud_remote]
type = "caldav"
url = "https://caldav.icloud.com/"
username = "your@icloud.com"
password.fetch = ["command", "cat", "~/.config/vdirsyncer/icloud_password"]

[storage icloud_local]
type = "filesystem"
path = "~/.local/share/vdirsyncer/calendars/"
fileext = ".ics"
各服务商地址：
  • iCloud: 
    https://caldav.icloud.com/
  • Google: 使用 
    google_calendar
    存储类型
  • Fastmail: 
    https://caldav.fastmail.com/dav/calendars/user/EMAIL/
  • Nextcloud: 
    https://YOUR.CLOUD/remote.php/dav/calendars/USERNAME/

2. Configure khal (
~/.config/khal/config
)

2. 配置khal（
~/.config/khal/config
）

ini
[calendars]
[[my_calendars]]
path = ~/.local/share/vdirsyncer/calendars/*
type = discover

[default]
default_calendar = Home
highlight_event_days = True

[locale]
timeformat = %H:%M
dateformat = %Y-%m-%d
ini
[calendars]
[[my_calendars]]
path = ~/.local/share/vdirsyncer/calendars/*
type = discover

[default]
default_calendar = Home
highlight_event_days = True

[locale]
timeformat = %H:%M
dateformat = %Y-%m-%d

3. Discover and sync

3. 发现日历并同步

bash
vdirsyncer discover   # First time only
vdirsyncer sync
bash
vdirsyncer discover   # 首次使用时执行
vdirsyncer sync