CLI Calendar Ls

ed calendar ls

Prints the events the app is holding whose start falls within the next --days days.

ed calendar ls [--days <n>] [--json]

Options

Name	Type / values	Default	What it does
--days <n>	integer, 0 or more	7	Only events starting within this many days. The cutoff is measured from the moment the command runs, not from midnight. A negative value exits 2.
--json	flag	off	Emit JSON on stdout. Long form only; there is no -j.

--help is generated by the parser, prints the usage summary on stdout and exits 0.

--json shape

A top level array, one object per event, in the same order the table prints them. Object keys are sorted, so allDay comes first and title last. null appears rather than a missing key, so the shape is stable across runs.

[
  {
    "allDay": true,
    "calendar": "Personal",
    "end": "2026-08-09T00:00:00Z",
    "location": null,
    "meetingURL": null,
    "start": "2026-08-08T00:00:00Z",
    "title": "Sarah's birthday"
  },
  {
    "allDay": false,
    "calendar": "Work",
    "end": "2026-08-08T11:30:00Z",
    "location": "https://meet.google.com/abc-defg-hij",
    "meetingURL": "https://meet.google.com/abc-defg-hij",
    "start": "2026-08-08T11:00:00Z",
    "title": "Standup"
  }
]

Key	Type	What it is
allDay	boolean	The event's all-day flag
calendar	string	The name of the calendar the event came from, "" when EventKit does not give one
end	string	End instant, ISO 8601 in UTC, for example 2026-08-08T11:30:00Z
location	string or null	The event's location field, verbatim, null when it has none
meetingURL	string or null	A detected video call link, null when none was found
start	string	Start instant, ISO 8601 in UTC
title	string	The event title, or Untitled when the event has none

No events is an empty array, [], and still exits 0.

Examples

ed calendar ls
ed calendar ls --days 1
ed calendar ls --days 14 --json
ed calendar ls --json | jq -r '.[] | select(.meetingURL) | .meetingURL'

Output

The table is four columns. WHEN is all day for an all-day event and EEE d MMM HH:mm in your own time zone and locale for everything else. LINK is the detected meeting URL, blank when there is none.

$ ed calendar ls --days 2
WHEN             TITLE             CALENDAR  LINK
all day          Sarah's birthday  Personal
Sat 8 Aug 11:00  Standup           Work      https://meet.google.com/abc-defg-hij
Sat 8 Aug 16:30  Dentist           Personal
Sun 9 Aug 09:00  Design review     Work      https://zoom.us/j/98213374412

location is in --json only; the table has no column for it. With nothing to show the header row is printed on its own:

$ ed calendar ls
WHEN  TITLE  CALENDAR  LINK

Behaviour

Nothing is written. ls reads, and the only side effect is on the app's side: answering the request makes the app refresh its calendar store first, so what you get is current rather than whatever the panel last drew, and the panel is current afterwards too.

The app must be running. ed checks for the menu bar helper before it posts anything, so a closed app fails immediately rather than after a timeout:

$ ed calendar ls
error: reading the calendar needs the Edith menu bar app to be running
hint: start Edith, then retry

With the app running, ed posts requestCalendarEvents on the app's own notification bus and waits up to 4 seconds for calendarEvents to come back. After one second of waiting it prints waiting for Edith to answer... on stderr, once. Silence past the deadline is diagnosed rather than reported as a bare timeout, in this order: the app stopped running, the Calendar extension is off, macOS has not granted calendar access, and only then "Edith did not answer for the calendar in time" with a hint that the running app may predate this command. Every one of those exits 4.

The app can also answer with a refusal instead of events, and those get their own wording:

$ ed calendar ls
error: the Calendar extension is off
hint: run `ed extensions enable calendar`

$ ed calendar ls
error: macOS has not granted Edith calendar access
hint: run `ed permissions request calendar`

Both exit 4. The second one is what you get when the grant is missing, denied, or write-only: the app answers only when EventKit reports full access.

--days is checked before anything is posted, so a bad value costs no round trip, though you have to write --days=-1 to get there: --days -1 is read as a missing value by the parser and exits 2 for that reason instead.

$ ed calendar ls --days=-1
error: --days cannot be negative
hint: pass 0 or more

Where to go next

• ed calendar, the rest of this group
• All ed commands