A CLI utility that parses ICS/iCalendar files and outputs events as JSON. Designed for use by AI agents to read calendar data and help users manage their schedules.
go install github.com/2gn/ics-cli@latestOr build from source:
git clone https://github.com/2gn/ics-cli
cd ics-cli
go build -o ics-cli .ics-cli [flags] [file]
| Argument | Description |
|---|---|
file |
Path to .ics file. If omitted, reads from stdin. |
| Flag | Description |
|---|---|
-p, --pretty |
Pretty-print JSON output (default: compact) |
--from DATE |
Include events starting on or after DATE |
--to DATE |
Include events starting on or before DATE |
-h, --help |
Show help |
DATE accepts YYYY-MM-DD or RFC3339 format. --from and --to can be used independently or together.
Read from a file:
ics-cli calendar.icsRead from stdin (pipe):
cat calendar.ics | ics-cli
curl -s https://example.com/calendar.ics | ics-cliPretty-print output:
ics-cli --pretty calendar.icsFilter by date range:
# Events in Q1 2024
ics-cli --from 2024-01-01 --to 2024-03-31 calendar.ics
# All events from today onwards
ics-cli --from 2024-06-01 calendar.ics
# All events up to a deadline
ics-cli --to 2024-12-31 calendar.icsOutputs a JSON array of event objects to stdout. Errors are written to stderr.
[
{
"uid": "[email protected]",
"summary": "Team Meeting",
"description": "Weekly sync to discuss progress and blockers.",
"start": "2024-01-15T09:00:00Z",
"end": "2024-01-15T10:00:00Z",
"all_day": false,
"location": "Conference Room A",
"status": "CONFIRMED",
"organizer": "mailto:[email protected]",
"attendees": [
"mailto:[email protected]",
"mailto:[email protected]"
],
"created": "2024-01-01T00:00:00Z",
"last_modified": "2024-01-10T12:00:00Z",
"url": "https://example.com/meeting"
},
{
"uid": "[email protected]",
"summary": "Company Holiday",
"start": "2024-01-20T00:00:00Z",
"end": "2024-01-21T00:00:00Z",
"all_day": true,
"status": "CONFIRMED"
}
]| Field | Type | Description |
|---|---|---|
uid |
string | Unique identifier of the event |
summary |
string | Event title |
description |
string | Event description/notes |
start |
string | Start time in RFC3339 UTC (2006-01-02T15:04:05Z) |
end |
string | End time in RFC3339 UTC |
all_day |
bool | true if this is an all-day event (no time component) |
location |
string | Physical or virtual location |
status |
string | Event status (e.g. CONFIRMED, TENTATIVE, CANCELLED) |
organizer |
string | Organizer (typically a mailto: URI) |
attendees |
array | List of attendees (typically mailto: URIs) |
created |
string | Creation timestamp in RFC3339 UTC |
last_modified |
string | Last modification timestamp in RFC3339 UTC |
url |
string | Associated URL |
rrule |
string | Recurrence rule (raw RRULE string, e.g. FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR) |
Fields with no value are omitted from output.
- All timestamps are in RFC3339 UTC format for easy parsing
- All-day events have
"all_day": truewith midnight UTC timestamps - Recurring events include the raw
rrulefield; individual occurrences are not expanded (v1) - Only
VEVENTcomponents are emitted;VTODOandVJOURNALare ignored - Output is always a JSON array (empty array
[]if no events found) - Exit code
0on success, non-zero on error