Manages macOS Calendar events and calendars from the terminal using the ical CLI. Full CRUD for both events and calendars. Supports natural language dates, r...
---
name: cal-cli
description: Manages macOS Calendar events and calendars from the terminal using the ical CLI. Full CRUD for both events and calendars. Supports natural language dates, recurrence rules, alerts, interactive mode, import/export (JSON/CSV/ICS), and multiple output formats. Use when the user wants to interact with Apple Calendar via command line, automate calendar workflows, or build scripts around macOS Calendar.
metadata:
author: sidv
version: "1.0"
compatibility: Requires macOS with Calendar.app. Requires Xcode Command Line Tools for building from source.
---
# ical — CLI for macOS Calendar
A Go CLI that wraps macOS Calendar. Sub-millisecond reads via cgo + EventKit. Single binary, no dependencies at runtime.
## Installation
```bash
go install github.com/BRO3886/ical/cmd/ical@latest
```
Or build from source:
```bash
git clone <repo-url> && cd ical
make build # produces bin/ical
```
## Quick Start
```bash
# List all calendars (shows sources, colors, types)
ical calendars
# Create a new calendar
ical calendars create "Projects" --source iCloud --color "#FF6961"
# Show today's agenda
ical today
# List events this week
ical list --from today --to "end of week"
# Add an event with natural language dates
ical add "Team standup" --start "tomorrow at 9am" --end "tomorrow at 9:30am" --calendar Work --alert 15m
# Show event details (row number from last listing)
ical show 2
# Delete an event (--force skips confirmation prompt, required in scripts/agents)
ical delete 2 --force
# Search for events
ical search "meeting" --from "30 days ago" --to "next month"
# Export events to ICS
ical export --format ics --from today --to "in 30 days" --output-file events.ics
```
## Command Reference
### Event CRUD
| Command | Aliases | Description |
| ------------ | --------------- | ----------------------- |
| `ical add` | `create`, `new` | Create an event |
| `ical show` | `get`, `info` | Show full event details |
| `ical update` | `edit` | Update event properties |
| `ical delete` | `rm`, `remove` | Delete an event |
### Event Views
| Command | Aliases | Description |
| -------------- | -------------- | ------------------------------ |
| `ical list` | `ls`, `events` | List events in a date range |
| `ical today` | — | Show today's events |
| `ical upcoming` | `next`, `soon` | Show events in the next N days |
### Search & Export
| Command | Aliases | Description |
| ------------ | ------- | --------------------------------------- |
| `ical search` | `find` | Search events by title, location, notes |
| `ical export` | — | Export events to JSON, CSV, or ICS |
| `ical import` | — | Import events from JSON or CSV file |
### Calendar Management
| Command | Aliases | Description |
| ------------------------- | ----------------- | ------------------------------------ |
| `ical calendars` | `icals` | List all calendars |
| `ical calendars create` | `add`, `new` | Create a new calendar |
| `ical calendars update` | `edit`, `rename` | Update a calendar (rename, recolor) |
| `ical calendars delete` | `rm`, `remove` | Delete a calendar and all its events |
### Skills & Other
| Command | Aliases | Description |
| ---------------------- | ------- | -------------------------------------------------- |
| `ical skills install` | — | Install ical agent skill for Claude Code / Codex |
| `ical skills uninstall` | — | Remove ical agent skill |
| `ical skills status` | — | Show skill installation status |
| `ical version` | — | Print version and build info |
| `ical completion` | — | Generate shell completions (bash/zsh/fish) |
For full flag details on every command, see [references/commands.md](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:
```bash
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:
```bash
# 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:
```bash
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](references/dates.md) for the full list.
### Interactive Mode
The `add` and `update` commands support `-i` for guided form-based input:
```bash
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:
```bash
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:
```bash
# 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):
```bash
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
```bash
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
```bash
ical upcoming --days 7 # Full week view
ical add "Planning" --start "monday at 9am" -i # Add events interactively
```
### Scripting with JSON output
```bash
# 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
```bash
# 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`](https://github.com/BRO3886/go-eventkit) directly:
```go
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](https://github.com/BRO3886/go-eventkit) 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
don't have the plugin yet? install it then click "run inline in claude" again.