Calendar CLI日历命令行工具

caloogy-calendar lets you — and AI tools in your terminal like Claude Code and Codex — add, read, change and sync events on your calendar.caloogy.com. Say “dentist tomorrow 3 to 4pm” and it's on your calendar; ask for your Feishu calendar to be copied over and it is.

caloogy-calendar 让你——以及你终端里的 AI 工具（Claude Code、Codex 等）——直接新建、查看、修改和同步 calendar.caloogy.com 上的日程。对 AI 说一句"明天下午三点到四点看牙医"，日程就进了日历；让它把飞书日历搬过来，也是一句话的事。

1Install安装

You need Python 3.9 or newer (macOS, Linux and Windows all work). Install with uv or pipx:

需要 Python 3.9 或更新版本（macOS、Linux、Windows 都可以）。用 uv 或 pipx 安装：

uv tool install "git+https://github.com/iamtheozzz/caloogy-cli#subdirectory=caloogy-work/calendar"

or

或者

pipx install "git+https://github.com/iamtheozzz/caloogy-cli#subdirectory=caloogy-work/calendar"

Check it works, and update later with uv tool upgrade caloogy-calendar (or pipx upgrade caloogy-calendar):

确认装好了；以后更新用 uv tool upgrade caloogy-calendar（或 pipx upgrade caloogy-calendar）：

caloogy-calendar --version

2Log in登录

caloogy-calendar login

1. The tool prints a link and an 8-character code like KQ7M-3XPA, and opens your browser.
2. Sign in to Caloogy if asked. The calendar page asks: “caloogy-calendar on your-mac wants to read and change your calendar.”
3. Check that the code on the page matches the one in your terminal, then choose Allow.
4. The terminal says Logged in as …. Done — this computer stays logged in.

1. 工具会打印一个链接和一个 8 位码（如 KQ7M-3XPA），并自动打开浏览器。
2. 如果需要就登录 Caloogy。日历页面会问："caloogy-calendar on 你的电脑 想读取和修改你的日历。"
3. 确认页面上的码和终端里的一样，点 允许。
4. 终端显示 Logged in as … 就好了，这台电脑之后一直保持登录。

Other login commands:

其他登录相关命令：

caloogy-calendar whoami        # which account this computer uses
caloogy-calendar logout        # revoke this computer's access
caloogy-calendar login --no-browser   # just print the link (e.g. on a server over SSH)

3Use it with your AI交给 AI 使用

Teach Claude Code and Codex how to use the tool (writes a skill file to ~/.claude/skills and ~/.codex/skills), then restart them:

让 Claude Code 和 Codex 学会用它（会把一份 skill 写进 ~/.claude/skills 和 ~/.codex/skills），然后重启它们：

caloogy-calendar install-skill

Only one of them? Add --claude or --codex. Another tool? --dir path/to/its/skills. Now just talk:

只用其中一个就加 --claude 或 --codex；别的工具用 --dir 它的skills目录。然后直接说话：

The skill tells the AI to check today's date before working out “tomorrow” or “Friday”, to ask before deleting several events, and to show you an import before writing it.

skill 里要求 AI：算"明天""周五"之前先查当天日期；删多个日程前先问你；批量导入前先给你看清单。

Commands命令

Every command accepts --json for machine-readable output, and --help.

每个命令都支持 --json（机器可读输出）和 --help。

caloogy-calendar add "Dentist" --date tomorrow --start 15:00 --end 16:00 --location "Main St"
caloogy-calendar add "Gym" --date 2026-10-30 --start 7am --duration 1h
caloogy-calendar add "Call mom" --date +2
caloogy-calendar list --days 7
caloogy-calendar update 2026-10-26-1a2b3c4d --start 17:00 --end 18:00
caloogy-calendar delete 2026-10-26-1a2b3c4d
caloogy-calendar friends
caloogy-calendar list --friend Sam --days 7

Dates: 2026-10-25, today, tomorrow, yesterday, +3 / -1 (days from today). Times: 15:00, 9:30, 3pm, or an ISO time like 2026-10-25T14:00+08:00 (converted to your computer's time zone; --tz Asia/Shanghai picks another).

日期：2026-10-25、today、tomorrow、yesterday、+3 / -1（相对今天的天数）。时间：15:00、9:30、3pm，或 ISO 时间如 2026-10-25T14:00+08:00（会换算成你电脑的时区；--tz Asia/Shanghai 可指定别的时区）。

How events work日程的规则

• One event, one day, local time. Start and end are wall-clock times (24-hour). 24:00 means midnight at the end of the day. An event without a start is an all-day item.
• No duplicates. “The same event” means same day + same start + same title. add and import never create a second copy, so a sync is safe to run again and again.
• Changing a time or title makes it a different event for syncing — re-importing after you renamed something in Feishu adds the new name and keeps the old one; delete the old one if you don't want it.
• Ids change with the event. An id like 2026-10-25-1a2b3c4d is printed by every command; after an update use the new id. If one says “No event with that id”, run list again.
• Across midnight: imported events are split per day (22:00–24:00 and 00:00–02:00). With add, add one piece per day.
• Same calendar as the website. What the CLI writes shows up on calendar.caloogy.com within 30 seconds (instantly on reload), and the other way round.

• 一条日程 = 一天、本地时间。开始/结束是墙上时间（24 小时制），24:00 表示当天午夜。没有开始时间的是全天事项。
• 不会重复。"同一个日程"= 同一天 + 同一开始时间 + 同一标题。add 和 import 都不会建第二份，所以同步可以放心反复跑。
• 改了时间或标题，同步时就算另一个日程——在飞书里改了名字再导入，会加上新名字、旧的还在；不要的话删掉旧的。
• ID 跟着日程变。每个命令都会打印 ID（如 2026-10-25-1a2b3c4d）；改过之后用新的 ID。提示"No event with that id"就先 list 一下。
• 跨午夜：导入时自动按天拆开（22:00–24:00 和 00:00–02:00）；用 add 时请每天各加一段。
• 和网页是同一份日历。命令行写进去的，30 秒内（刷新立刻）出现在 calendar.caloogy.com；反过来也一样。

Sync with Feishu / Lark和飞书同步

You need the Feishu CLI — lark-cli (or feishu-cli) — logged in with calendar permission (lark-cli auth login). The easiest way: ask your AI to do it. Here's what it runs.

需要先装好飞书命令行 lark-cli（或 feishu-cli），并用有日历权限的账号登录（lark-cli auth login）。最省事的是直接让 AI 做，下面是它实际跑的命令。

Feishu → Caloogy飞书 → Caloogy

# 1. dump the Feishu events (user identity)
lark-cli calendar +agenda --as user --start 2026-11-01 --end 2026-11-30 > feishu.json
# 2. preview, then import
caloogy-calendar import feishu.json --dry-run
caloogy-calendar import feishu.json

With feishu-cli instead: feishu-cli calendar list-events <calendar_id> --start-time 2026-11-01T00:00:00+08:00 --end-time 2026-11-30T23:59:59+08:00 -o json > feishu.json. Cancelled events are skipped; titles, locations, attendees and the video-call link come along. Feishu all-day events end on their last day (that's the default for JSON input).

用 feishu-cli 的话：feishu-cli calendar list-events <日历ID> --start-time 2026-11-01T00:00:00+08:00 --end-time 2026-11-30T23:59:59+08:00 -o json > feishu.json。已取消的日程会跳过；标题、地点、参与人、视频会议链接都会带过来。飞书全天日程的结束日期算在日程内（JSON 输入的默认就是这样）。

Caloogy → FeishuCaloogy → 飞书

# what's in Caloogy but not yet in Feishu
lark-cli calendar +agenda --as user --start 2026-11-01 --end 2026-11-30 > feishu.json
caloogy-calendar export --from 2026-11-01 --to 2026-11-30 --not-in feishu.json --json
# then for each event
lark-cli calendar +create --as user --summary "Dentist" --start "2026-11-03T15:00+08:00" --end "2026-11-03T16:00+08:00"

export gives every event a start_iso / end_iso with your time-zone offset, ready to pass to +create. Items without a time have "all_day": true. Ticked-off items are left out unless you add --include-done.

export 给每条日程都带上含时区的 start_iso / end_iso，可以直接传给 +create。没有时间的事项是 "all_day": true。已打勾的默认不导出，要导出加 --include-done。

Google, Apple, OutlookGoogle / Apple / Outlook

Any calendar that can export or import .ics files works:

能导入导出 .ics 文件的日历都可以：

caloogy-calendar import ~/Downloads/calendar.ics --dry-run   # into Caloogy
caloogy-calendar export --days 60 --format ics > caloogy.ics   # out of Caloogy

Repeating events inside a raw .ics file are skipped (the tool tells you how many) — export single occurrences from the other calendar instead. Google Calendar API JSON (items with start.dateTime) and any plain list like [{"title": "…", "start": "2026-11-03T15:00+08:00", "end": "…"}] work too.

原始 .ics 里的重复日程会跳过（会告诉你跳过了几个），请从对方日历导出展开后的单次日程。Google Calendar API 的 JSON（items 里带 start.dateTime），以及 [{"title": "…", "start": "2026-11-03T15:00+08:00", "end": "…"}] 这样的简单列表也都能导入。

Security & privacy安全与隐私

• The tool gets a token only after you press Allow while signed in. It's stored in ~/.config/caloogy/calendar.json, readable only by you. The server keeps just a fingerprint of it.
• The token can read and change your calendar events, and read (never change) the calendars of your friends — people you've accepted in Caloogy Work. Nothing else: not your settings, other Caloogy products, or anyone else's calendar.
• Your friends' tools can likewise read your calendar. Want to keep the details to yourself? Turn on Hide details from friends in the calendar's left sidebar (under Friends; on a phone, behind the calendar icon at the top right). Then friends — on the website and through their AI / command line — see only when you're busy, as “Busy” blocks: no titles, places or people. Or remove someone as a friend in Caloogy Work.
• See every connected computer on calendar.caloogy.com → your avatar → Command-line access, and Revoke any of them. caloogy-calendar logout revokes the current one.
• When you ask your AI to sync, your events pass through that AI tool like anything else you show it.

• 只有你登录状态下点了允许，工具才拿到令牌。令牌存在 ~/.config/caloogy/calendar.json，只有你能读；服务器上只存它的指纹。
• 令牌能读写你的日程，并能只读查看你好友（在 Caloogy Work 里互相通过的人）的日历；别的都碰不到：设置、Caloogy 其他产品、非好友的日历都不行。
• 反过来，你好友的命令行工具 / AI 也能读到你的日历。不想让好友看到详情，就在日历左侧栏"好友"下面打开对好友隐藏详情（手机上在右上角日历图标里）：之后好友在网页上、用 AI / 命令行都只能看到你几点到几点"忙碌"，看不到标题、地点和参与人。也可以在 Caloogy Work 里删掉这个好友。
• 在 calendar.caloogy.com → 头像 → 命令行访问 里能看到所有已连接的电脑，可以逐个撤销；caloogy-calendar logout 撤销当前这台。
• 让 AI 帮你同步时，日程内容会经过那个 AI 工具，和你给它看的其他内容一样。

Troubleshooting常见问题

Exit codes: 0 ok · 1 failed · 2 bad arguments · 3 not logged in.

退出码：0 成功 · 1 失败 · 2 参数不对 · 3 未登录。