Skills cal-cli

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.

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/bro3886/ical-cli" ~/.claude/skills/clawdbot-skills-cal-cli && rm -rf "$T"

manifest: skills/bro3886/ical-cli/SKILL.md

source content

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

go install github.com/BRO3886/ical/cmd/ical@latest

Or build from source:

git clone <repo-url> && cd ical
make build    # produces bin/ical

Quick Start

# 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.

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:

(minutes),

(hours),

(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