ics-cli

README

ics

A small, fast CLI for inspecting iCalendar (.ics) files and feeds — like jq, but for calendars.

$ ics https://example.com/team.ics
📅 Open Collective Team
   24 events between 2025-01-15 and 2026-12-31  (1 recurring series, expanded through 2027-05-04)

   Next:
    Mon May 11  11:00  Weekly standup  @ Zoom ↻

   Then:
    Mon May 18  11:00  Weekly standup  @ Zoom ↻
    Wed May 20  12:00  Board sync  @ Online
    Mon Jun 01         Company off-site  @ Lisbon

   Last:
    Thu Dec 31  18:00  EOY retro  @ Anywhere

Features

• Pipe-friendly. Reads from a path, an http(s):// / webcal:// URL, or stdin.
• Four modes. Default summary, --list for paginated tables, --show for a single event, --json for machine-readable output.
• Filters. --since, --until, --search, --upcoming.
• Recurring events. Expands RRULE series within the requested window (capped at one year by default; override with --expand-until).
• Colors. Auto-detected, with --color=auto|always|never, --no-color, and NO_COLOR env var support.
• Time zones. Render in any IANA zone via --tz.

Installation

Pre-built release binaries

Download the archive for your platform from the Releases page, extract, and put ics on your PATH.

# macOS arm64 example — adjust URL for your platform
curl -L https://github.com/xdamman/ics-cli/releases/latest/download/ics_$(uname -s | tr A-Z a-z)_$(uname -m).tar.gz \
  | tar xz -C /tmp
sudo mv /tmp/ics_*/ics /usr/local/bin/
ics --version

Binaries are built for linux/amd64, linux/arm64, darwin/amd64, and darwin/arm64. Each release includes checksums.txt.

With go install

go install github.com/xdamman/ics-cli@latest

The binary lands in $(go env GOBIN) (or $(go env GOPATH)/bin).

From source

git clone https://github.com/xdamman/ics-cli.git
cd ics-cli
make build              # produces ./ics (~7 MB, stripped)
make install            # installs to $GOBIN

Usage

ics [flags] [file|url|-]

Examples

# Quick overview of a file
ics calendar.ics

# Fetch a remote feed and pipe through ics
curl -s https://example.com/team.ics | ics

# Filter to a window
ics calendar.ics --since 2026-01-01 --until 2026-06-30

# Just upcoming events as a list, top 10
ics calendar.ics --upcoming --list -n 10

# Inspect a single event by 1-based index or by UID
ics calendar.ics --show 3
ics calendar.ics --show abcd-1234@example.com

# Machine-readable
ics calendar.ics --json | jq '.events[] | select(.location == "Zoom").summary'

# Render in a specific time zone
ics calendar.ics --tz America/New_York

Date input

--since, --until, and --expand-until all accept:

• ISO dates: 2026-05-04, 20260504
• Keywords: today, tomorrow, yesterday, now
• Relative: 7d, -7d, +30d, 2w, 1m, 1y

Flags

Flag	Description
--json	Output JSON
-l, --list	Tabular list of events
-s, --show ID	Show one event by UID or 1-based index
--since DATE	Include events with start ≥ DATE
--until DATE	Include events with start ≤ DATE
--upcoming	Shorthand for --since today
--search QUERY	Substring match in summary / description / location
--expand-until DATE	Expand RRULEs through DATE (default: today + 1y)
-n, --limit N	Max events to show (0 = all)
--skip N	Skip N events
--first N	Keep only the first N events (after filters)
--last N	Keep only the last N events (after filters)
--next N	Summary: number of upcoming events under "Then:" (default 3)
--tz ZONE	IANA time zone for rendering (default: local)
--color WHEN	auto, always, or never
--no-color	Alias for --color=never
--version	Print version

JSON envelope

Every JSON mode emits the same envelope so scripts can treat output uniformly:

{
  "calendar": { "name": "...", "timezone": "..." },
  "range":    { "since": "...", "until": "...", "expandedThrough": "..." },
  "count":    24,
  "total":    24,
  "events":   [ { "uid": "...", "summary": "...", "start": "...", "end": "...", "allDay": false, "recurring": false } ]
}

In summary mode the envelope also includes first, last, nextUpcoming, and upcoming. In --show mode events has a single element and an index field is added.

Development

make build         # build a stripped binary
make test          # run tests
make fmt vet       # format & lint
make tidy          # go mod tidy
make release-archives VERSION=v0.1.0   # cross-compile all platforms locally

Releases are produced automatically by .github/workflows/release.yml when a v* tag is pushed:

git tag v0.1.0
git push origin v0.1.0

License

MIT