nanocal

Experimental. Shouldn't be considered production ready yet.

A Swift CLI for reading and managing Apple Calendar events on macOS.

Uses EventKit for full calendar access. Human-readable text by default, --json for structured output.

Install

./install.sh

This builds a release binary and symlinks it to ~/bin/nanocal.

Requirements

• macOS 14 (Sonoma) or later
• Swift 6.0+ (included with Xcode 16+)
• ~/bin in your PATH

Permissions

Grant your terminal app in System Settings > Privacy & Security:

• Calendars — full access (prompted on first run)

Commands

# List all calendars
nanocal calendars

# List events in a date range (default: today)
nanocal events --from "2026-02-14" --to "2026-02-15"
nanocal events -c "Work" --search "standup"

# Today's events
nanocal today

# Upcoming events (default: 7 days)
nanocal upcoming --days 14

# Full event details
nanocal show --id "EVENT-UUID"

# Create an event
nanocal create -c "Work" --title "Standup" --start "2026-02-14T10:00:00" --end "2026-02-14T10:30:00"

# Create an all-day event
nanocal create -c "Personal" --title "Vacation" --start "2026-03-01" --end "2026-03-02" --allday

# Update an event
nanocal update --id "EVENT-UUID" --title "New title"

# Delete an event
nanocal delete --id "EVENT-UUID"

# Per-command help
nanocal help events

Global options

Flag	Description
--json	Output JSON instead of human-readable text
--ids	Show event IDs in text output
--limit N	Max results to return
--offset N	Skip first N results (pagination)

Output format

Default output is human-readable text with relative dates ("Today", "Tomorrow", "Mar 14, 2026"). Use --json for structured JSON with ISO 8601 dates.

JSON shapes:

• calendars: identifier, title, type, writable, color
• events/today/upcoming: id, title, startDate, endDate, isAllDay, location, calendar
• show: all above plus notes, url, status, availability, attendees[], organizer, recurrence
• create: returns event summary
• update: returns full event detail
• delete: {"deleted": "<id>"}

Testing

TEST.md contains integration test instructions designed to be run by a coding agent (like Claude Code). To run them:

claude -p "Read TEST.md and run all the tests. Report pass/fail for each."

Use as a Claude Code skill

Symlink this repo into your project's .claude/skills/:

ln -s /path/to/nanocal /your/project/.claude/skills/nanocal

The repo root contains a SKILL.md that teaches Claude Code how to use nanocal for calendar access.

License

MIT