ekctl

# ekctl - macOS Calendar & Reminders CLI

Use the `ekctl` command-line tool to manage Calendar events and Reminders on macOS. All output is JSON for easy parsing.

## Prerequisites

Ensure ekctl is installed:
```bash
brew tap schappim/ekctl && brew install ekctl
```

If not installed, guide the user to install it first.

## Workflow

### 1. Check for aliases first

Before any calendar/reminder operation, check if the user has aliases configured:
```bash
ekctl alias list
```

If aliases exist, use them instead of raw IDs. If no aliases exist, help the user set them up after listing calendars.

### 2. List available calendars

```bash
ekctl list calendars
```

This returns both event calendars (`type: "event"`) and reminder lists (`type: "reminder"`).

### 3. Set up aliases for convenience

Help users create aliases for frequently used calendars:
```bash
ekctl alias set work "CALENDAR_ID"
ekctl alias set personal "CALENDAR_ID"
ekctl alias set groceries "REMINDER_LIST_ID"
```

### 4. Perform requested operations

Use the appropriate command based on what the user wants to do. See `command-reference.md` for all commands.

## Date Format

**Always use ISO 8601 format with timezone:**

| Example | Description |
|---------|-------------|
| `2026-01-15T09:00:00Z` | 9:00 AM UTC |
| `2026-01-15T09:00:00+10:00` | 9:00 AM AEST |
| `2026-01-15T00:00:00Z` | Start of day (midnight UTC) |
| `2026-01-15T23:59:59Z` | End of day |

**Generate dates dynamically when needed:**
```bash
# Today at midnight UTC
TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")

# Tomorrow at midnight UTC
TOMORROW=$(date -u -v+1d +"%Y-%m-%dT00:00:00Z")

# Next week
NEXT_WEEK=$(date -u -v+7d +"%Y-%m-%dT00:00:00Z")

# Specific time today (e.g., 2pm)
TODAY_2PM=$(date -u +"%Y-%m-%dT14:00:00Z")
```

## Common Patterns

### List today's events
```bash
TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")
TOMORROW=$(date -u -v+1d +"%Y-%m-%dT00:00:00Z")
ekctl list events --calendar work --from "$TODAY" --to "$TOMORROW"
```

### List this we