Commands

Overview

ical provides commands for managing macOS Calendar events and calendars. Every command that displays data supports --output (-o) with table, json, or plain formats.

Global Flags

These flags are available on all commands:

ical calendars

Manage calendars. Running without a subcommand lists all calendars.

ical calendars
ical cals
ical calendars -o json

Displays the calendar name, source (iCloud, Google, etc.), type, color, and read-only status. Useful for finding the exact calendar name to pass to -c and discovering available sources for creating new calendars.

ical calendars create

Create a new calendar. Requires --source to specify the account.

# Create with flags
ical calendars create "Projects" --source iCloud --color "#FF6961"

# Interactive mode
ical calendars create -i

Flags

Run ical calendars to see available sources from existing calendars.

ical calendars update

Update an existing calendar (rename or recolor).

# Update by name
ical calendars update "Projects" --title "Archived" --color "#8295AF"

# Interactive mode (guided form)
ical calendars update "Projects" -i

# Interactive picker (no argument)
ical calendars update -i

Flags

Subscribed and birthday calendars cannot be updated (immutable).

ical calendars delete

Permanently delete a calendar and all its events.

# Delete by name (with confirmation)
ical calendars delete "Projects"

# Skip confirmation
ical calendars delete "Projects" --force

# Interactive picker (no argument)
ical calendars delete

Flags

Subscribed and birthday calendars cannot be deleted (immutable).

ical list

List events within a date range.

ical list -f "next monday" -t "next friday"
ical list -f today -t "in 7 days" -c Work

Flags

Events are displayed with row numbers (#1, #2, …) that can be used with show, update, and delete. The row mapping is cached to ~/.ical-last-list so subsequent commands can reference events by number. When events span multiple years, the date column includes the year for disambiguation.

# List, then act on event #2
ical list -f today -t "next friday"
ical show 2

# Filter by multiple calendars
ical list -f today -t "in 7 days" -c Work -c Personal

ical today

Show today’s events. A convenience shortcut for ical list -f today -t today.

ical today
ical today -c Work
ical today -o json

Flags

ical upcoming

Show events for the next N days (default: 7).

ical upcoming
ical upcoming -d 30
ical upcoming -d 14 -c Work --exclude-calendar Birthdays

Flags

ical show

Display detailed information about a single event.

# Interactive picker (no argument)
ical show

# By row number from last listing
ical show 2

# By full or partial event ID
ical show 577B8983-DF44-4665-B0F9-ABCD1234

# By exact event ID (for scripts and agents)
ical show --id "577B8983-DF44-4665-B0F9-ABCD1234:abc"

Flags

Event Selection

Events can be selected four ways:

1. Interactive picker — Run with no argument to get a searchable list
2. Row number — Use #N from the last list, today, or upcoming output
3. Event ID — Pass a full or partial eventIdentifier as a positional arg
4. --id flag — Full event ID, exact match only (preferred for scripts/agents)

--id and a positional argument are mutually exclusive.

The show command displays title, calendar, start/end times, location, notes, alerts, recurrence rules, URL, and attendees.

ical add

Create a new calendar event.

# With flags
ical add "Team Standup" -s "tomorrow 9am" -e "tomorrow 9:30am" -c Work

# Interactive guided form
ical add -i

Flags

--invite and --travel are not available in interactive (-i) mode. Inviting an attendee makes the calendar account send a real invitation email on save, and the organizer (you) is added automatically.

Examples

# All-day event
ical add "Company Holiday" -s 2026-03-15 --all-day -c Work

# With location and multiple alerts
# Passing any --alert gives the event exactly those alerts — the calendar's
# default alerts are not merged in. Omit --alert to inherit the default.
ical add "Dinner" -s "friday 7pm" -e "friday 9pm" \
  -l "The Restaurant, 123 Main St" --alert 1h --alert 15m

# Suppress the calendar's default alerts (e.g. for mirrored busy blocks)
ical add "Busy block" -s "tomorrow 9am" -e "tomorrow 10am" --no-alert

# Weekly recurring event
ical add "Weekly Sync" -s "next monday 10am" -e "next monday 11am" \
  --repeat weekly --repeat-days mon -c Work

# Recurring with end date
ical add "Daily Standup" -s "tomorrow 9am" -e "tomorrow 9:15am" \
  --repeat daily --repeat-until "2026-12-31" -c Work

# With timezone
ical add "NYC Meeting" -s "tomorrow 2pm" -e "tomorrow 3pm" \
  --timezone "America/New_York" -c Work

Interactive Mode

The -i flag launches a guided form where you fill in each field step by step. The form uses the Catppuccin theme and supports calendar selection from a dropdown.

ical update

Update an existing event.

# Interactive picker + guided form
ical update -i

# Update by row number
ical update 2 --title "New Title"

# Reschedule
ical update 3 -s "tomorrow 2pm" -e "tomorrow 3pm"

# Update future occurrences of recurring event
ical update 1 --span future --title "New Series Name"

# By exact event ID (for scripts and agents)
ical update --id "577B8983-DF44:abc" --title "New Title"

Flags

update applies changes immediately — there is no confirmation prompt and no --force flag. --id and a positional argument are mutually exclusive.

ical delete

Delete one or more events with a confirmation prompt.

# Interactive picker with confirmation
ical delete

# Delete by row number
ical delete 3

# Skip confirmation
ical delete 3 -f

# Batch delete multiple events at once
ical delete 1 2 3 --force

# Delete future occurrences of recurring event
ical delete 2 --span future

# By exact event ID (for scripts and agents)
ical delete --id "577B8983-DF44:abc" --force

Flags

Batch Delete

Multiple row numbers or event IDs can be passed as positional arguments to delete several events in a single operation:

ical list --from today --to "next friday"   # Shows #1, #2, #3...
ical delete 1 3 5 --force                   # Delete events #1, #3, #5

Batch delete uses go-eventkit’s DeleteEvents API for efficient single-call deletion. Each event is resolved individually, and per-event errors are reported without aborting the entire batch.

Always pass --force when running non-interactively (scripts, agents). There is no --confirm flag. --id and a positional argument are mutually exclusive. --id only works for single event deletion.

ical search

Search events by title and description.

ical search "standup"
ical search "meeting" -c Work -f "1 month ago" -t "in 1 month"

Flags

ical join

Open the video-conference link of the current or next meeting. With no argument, ical picks the event you most likely want to join: one happening now (most recently started wins), otherwise the soonest upcoming event with a link. With an argument, it resolves a row number or event ID like show.

ical join              # open the current/next meeting link in the browser
ical join --print      # print just the URL (pipe-friendly)
ical join 3            # join the event at row 3 of the last listing

Flags

Links are detected for Zoom, Google Meet, Teams, FaceTime, Webex, Jitsi, Whereby, Chime, and GoToMeeting, whether in the event’s URL field, location, or notes.

ical rsvp

Respond to an event invitation. The first argument is your response; the second optionally selects the event by row number or ID. With no event argument, an interactive picker is shown. On a server-backed calendar this sends the reply to the organizer.

ical rsvp accepted 3       # accept the event at row 3
ical rsvp declined <id>    # decline by event ID
ical rsvp tentative        # pick interactively

Response words: accepted, declined, tentative (aliases yes/no/maybe).

ical free

Look up free/busy availability for one or more people over a time range. Requires an Exchange or Google Workspace account — iCloud does not support availability lookups.

ical free alice@example.com
ical free alice@example.com bob@example.com --from "monday 9am" --to "monday 6pm"

Flags

Each person’s busy blocks are printed; an address with no busy periods shows “free for the whole window”.

ical inbox

List event invitations awaiting your response (the Calendar notification inbox).

ical inbox
ical inbox -o json

Invitations carry no stable ID — respond with ical rsvp <status> (interactive picker) or find the event with ical list and use its row number.

ical export

Export events to a file or stdout.

# Export to JSON
ical export -f 2026-01-01 -t 2026-12-31 --format json > events.json

# Export to CSV
ical export -c Work --format csv --output-file work-events.csv

# Export to ICS (RFC 5545)
ical export --format ics --output-file calendar.ics

Flags

Formats

• JSON: Full event data including IDs, timestamps, recurrence rules
• CSV: Tabular format suitable for spreadsheets
• ICS: RFC 5545 iCalendar format, compatible with any calendar app

ical import

Import events from a JSON or CSV file.

ical import events.json
ical import events.csv -c Personal
ical import events.json --dry-run

Flags

The format is auto-detected from the file extension (.json or .csv).

ical skills

Manage the embedded AI agent skill. ical ships with an agent skill baked into the binary that teaches AI coding agents (Claude Code, Codex CLI, OpenClaw, GitHub Copilot, Cursor, Windsurf, Augment) how to use it.

ical skills install

Install the skill to the selected agent’s skill directory. Without --agent, shows an interactive picker. In interactive mode, a confirmation prompt shows exactly which paths will be created before writing anything. The skill files are the same documentation published at ical.sidv.dev/docs.

# Preview what would be installed (no files written)
ical skills install --dry-run

# Interactive — pick which agents, then confirm
ical skills install

# Direct
ical skills install --agent claude    # → ~/.claude/skills/ical-cli/
ical skills install --agent codex     # → ~/.codex/skills/ical-cli/
ical skills install --agent openclaw  # → ~/.openclaw/skills/ical-cli/
ical skills install --agent others    # → ~/.agents/skills/ical-cli/
ical skills install --agent all       # All agents

Flags

Supported targets:

• claude → ~/.claude/skills/ical-cli/ — works with Claude Code, GitHub Copilot, Cursor, OpenCode, Augment
• codex → ~/.codex/skills/ical-cli/ — works with Codex CLI
• openclaw → ~/.openclaw/skills/ical-cli/ — works with OpenClaw
• others → ~/.agents/skills/ical-cli/ — works with Copilot, Windsurf, OpenCode, Augment

ical skills uninstall

Remove the skill from the selected agent’s skill directory.

ical skills uninstall
ical skills uninstall --agent claude

Flags

ical skills status

Show where skills are installed and whether they match the current binary version.

ical skills status

If installed skills are outdated (from a previous version), ical will show a warning and prompt you to run ical skills install to update them.

ical version

Display the installed version of ical.

ical version

ical completion

Generate shell completion scripts.

# Bash
ical completion bash > /usr/local/etc/bash_completion.d/ical

# Zsh
ical completion zsh > "${fpath[1]}/_ical"

# Fish
ical completion fish > ~/.config/fish/completions/ical.fish

After generating, restart your shell or source the completion file to activate.