Cal Cli

Command Reference

Event CRUD

Event Views

Search & Export

Calendar Management

Skills & Other

For full flag details on every command, see references/commands.md.

Key Concepts

Row Numbers

Event listings display row numbers (#1, #2, #3...) alongside events. These are cached to ~/.ical-last-list so you can reference them in subsequent commands:

ical list --from today --to "next week"   # Shows #1, #2, #3...
ical show 2                                # Show details for row #2
ical update 3 --title "New title"          # Update row #3
ical delete 1 --force                      # Delete row #1 (skip confirmation)
ical delete 1                              # Delete row #1 (prompts for confirmation)

Row numbers reset each time you run a list/today/upcoming command. With no arguments, show, update, and delete launch an interactive picker instead.

Event ID flag (for scripts and agents)

When you have a full event ID (from -o json output), use --id for exact lookup with no prefix matching:

# Get event ID from JSON output
EVENT_ID=$(ical today -o json | jq -r '.[0].id')

# Use --id for reliable exact lookup
ical show --id "$EVENT_ID"
ical update --id "$EVENT_ID" --title "New title"
ical delete --id "$EVENT_ID" --force

Important for scripting:

• ical delete prompts for interactive confirmation by default. Always pass --force (or -f) when running non-interactively. There is no --confirm flag.
• ical update does not require confirmation and has no --force flag — just run it directly with the flags you want to change.
• --id and a positional argument are mutually exclusive — passing both returns an error.

Natural Language Dates

Date flags (--from, --to, --start, --end, --due) accept natural language:

ical list --from today --to "next friday"
ical add "Lunch" --start "tomorrow at noon" --end "tomorrow at 1pm"
ical search "standup" --from "2 weeks ago"
ical upcoming --days 14

Supported patterns: today, tomorrow, next monday, in 3 hours, eod, eow, this week, 5pm, mar 15, 2 days ago, and more. See references/dates.md for the full list.

Interactive Mode

The add and update commands support -i for guided form-based input:

ical add -i        # Multi-page form: title, calendar, dates, location, recurrence
ical update 2 -i   # Pre-filled form with current event values

The show, update, and delete commands accept 0 arguments to launch an interactive event picker:

ical show          # Pick from upcoming events
ical delete        # Pick an event to delete

Output Formats

All read commands support -o / --output:

• table (default) — formatted table with borders and color
• json — machine-readable JSON (ISO 8601 dates)
• plain — simple text, one item per line

The NO_COLOR environment variable and --no-color flag are respected.

Recurrence

Events can repeat with flexible rules:

# Daily standup
ical add "Standup" --start "tomorrow at 9am" --repeat daily

# Every 2 weeks on Mon and Wed
ical add "Team sync" --start "next monday at 10am" --repeat weekly --repeat-interval 2 --repeat-days mon,wed

# Monthly for 6 months
ical add "Review" --start "mar 1 at 2pm" --repeat monthly --repeat-count 6

# Yearly until a date
ical add "Anniversary" --start "jun 15" --repeat yearly --repeat-until "2030-06-15"

Use --repeat none on update to remove recurrence. Use --span future to update/delete this and all future occurrences.

Alerts

Add reminders before an event with the --alert flag (repeatable):

ical add "Meeting" --start "tomorrow at 2pm" --alert 15m          # 15 minutes before
ical add "Flight" --start "mar 15 at 8am" --alert 1h --alert 1d   # 1 hour + 1 day before

Supported units: m (minutes), h (hours), d (days).

Common Workflows

Daily review

ical today                                 # See today's agenda
ical upcoming --days 1                     # Same as today
ical list --from today --to "end of week"  # Rest of the week

Weekly planning

ical upcoming --days 7                           # Full week view
ical add "Planning" --start "monday at 9am" -i  # Add events interactively

Scripting with JSON output

# Count today's events
ical today -o json | jq 'length'

# Get titles of upcoming events
ical upcoming -o json | jq -r '.[].title'

# Find events on a specific calendar
ical list --from today --to "in 30 days" --calendar Work -o json | jq '.[].title'

# List calendar names (field is "title", not "name")
ical calendars -o json | jq -r '.[].title'

# Get calendar IDs and names
ical calendars -o json | jq -r '.[] | "\(.id) \(.title)"'

Calendar JSON fields: id, title, type, color, source, readOnly Event JSON fields: id, title, start_date, end_date, calendar, calendar_id, location, notes, url, all_day, recurrence, alerts

Backup and restore

# Export all events from the past year
ical export --from "12 months ago" --to "in 12 months" --format json --output-file backup.json

# Export as ICS for other calendar apps
ical export --from today --to "in 6 months" --format ics --output-file events.ics

# Import from backup
ical import backup.json --calendar "Restored"

Public Go API

For programmatic access to macOS Calendar, use go-eventkit directly:

import "github.com/BRO3886/go-eventkit/calendar"

client, _ := calendar.New()
events, _ := client.Events(from, to, calendar.WithCalendarName("Work"))
event, _ := client.CreateEvent(calendar.CreateEventInput{
    Title:        "Team Meeting",
    StartDate:    start,
    EndDate:      end,
    CalendarName: "Work",
})

See go-eventkit docs for the full API surface.

Limitations

• macOS only — requires EventKit framework via cgo
• No attendee management — attendees and organizer are read-only (Apple limitation)
• Subscribed/birthday calendars are read-only — cannot create events on these
• Event IDs are calendar-scoped — the UUID prefix before : is the calendar ID, not event-specific. Use row numbers or the interactive picker instead of raw IDs