Skill: bro3886/ical-cli (version 0.6.0)

--- name: cal-cli description: 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. metadata: author: sidv version: "1.0" compatibility: Requires macOS with Calendar.app. Requires Xcode Command Line Tools for building from source. --- # 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 ```bash go install github.com/BRO3886/ical/cmd/ical@latest ``` Or build from source: ```bash git clone <repo-url> && cd ical make build # produces bin/ical ``` ## Quick Start ```bash # 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](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: ```bash 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: ```bash # 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: ```bash 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](references/dates.md) for the full list. ### Interactive Mode The `add` and `update` commands support `-i` for guided form-based input: ```bash 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: ```bash 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: ```bash # 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): ```bash 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: `m` (minutes), `h` (hours), `d` (days). ## Common Workflows ### Daily review ```bash 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 ```bash ical upcoming --days 7 # Full week view ical add "Planning" --start "monday at 9am" -i # Add events interactively ``` ### Scripting with JSON output ```bash # 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 ```bash # 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`](https://github.com/BRO3886/go-eventkit) directly: ```go 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](https://github.com/BRO3886/go-eventkit) 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

path: references/commands.md
content: # Complete Command Reference

## ical calendars

Manage calendars. Running without a subcommand lists all calendars.

```bash
ical calendars
ical cals
ical calendars -o json
```

Aliases: `cals`

### ical calendars create

Create a new calendar. Title can be passed as a positional argument or via `--title`.

```bash
ical calendars create "Projects" --source iCloud --color "#FF6961"
ical calendars create -i
```

| Flag              | Short | Description                                | Default |
| ----------------- | ----- | ------------------------------------------ | ------- |
| `--title`         | `-T`  | Calendar title                             | —       |
| `--source`        | `-s`  | Account source (required, e.g., "iCloud")  | —       |
| `--color`         | —     | Calendar color (hex, e.g., "#FF6961")      | —       |
| `--interactive`   | `-i`  | Interactive mode with guided prompts       | false   |

Aliases: `add`, `new`

### ical calendars update

Update an existing calendar (rename, recolor). With no arguments, shows an interactive picker.

```bash
ical calendars update "Projects" --title "Archived" --color "#8295AF"
ical calendars update "Projects" -i
ical calendars update -i
```

| Flag              | Short | Description                              | Default |
| ----------------- | ----- | ---------------------------------------- | ------- |
| `--title`         | `-T`  | New calendar title                       | —       |
| `--color`         | —     | New calendar color (hex)                 | —       |
| `--interactive`   | `-i`  | Interactive mode with guided prompts     | false   |

Aliases: `edit`, `rename`

### ical calendars delete

Permanently delete a calendar and all its events. With no arguments, shows an interactive picker.

```bash
ical calendars delete "Projects"
ical calendars delete "Projects" --force
ical calendars delete
```

| Flag      | Short | Description              | Default |
| --------- | ----- | ------------------------ | ------- |
| `--force` | `-f`  | Skip confirmation prompt | false   |

Aliases: `rm`, `remove`

---

## ical list

List events within a date range. Defaults to today if no range specified.

```bash
ical list
ical list --from today --to "next friday"
ical list --calendar Work --sort title
ical ls --from "mar 1" --to "mar 31" --all-day
ical list --from today --to "in 30 days" --exclude-calendar Birthdays -o json
```

| Flag                 | Short | Description                               | Default         |
| -------------------- | ----- | ----------------------------------------- | --------------- |
| `--from`             | `-f`  | Start date (natural language or ISO 8601) | Today           |
| `--to`               | `-t`  | End date (natural language or ISO 8601)   | From + 24 hours |
| `--calendar`         | `-c`  | Filter by calendar name                   | All calendars   |
| `--calendar-id`      | —     | Filter by calendar ID                     | —               |
| `--search`           | `-s`  | Search title, location, notes             | —               |
| `--all-day`          | —     | Show only all-day events                  | false           |
| `--sort`             | —     | Sort by: start, end, title, calendar      | start           |
| `--limit`            | `-n`  | Max events to display (0 = unlimited)     | 0               |
| `--exclude-calendar` | —     | Exclude calendars by name (repeatable)    | —               |

Aliases: `ls`, `events`

---

## ical today

Show today's events. Shortcut for `ical list --from today --to tomorrow`.

```bash
ical today
ical today --calendar Work
ical today -o json
ical today --exclude-calendar Birthdays
```

| Flag                 | Short | Description                            | Default       |
| -------------------- | ----- | -------------------------------------- | ------------- |
| `--calendar`         | `-c`  | Filter by calendar name                | All calendars |
| `--calendar-id`      | —     | Filter by calendar ID                  | —             |
| `--search`           | `-s`  | Search title, location, notes          | —             |
| `--all-day`          | —     | Show only all-day events               | false         |
| `--sort`             | —     | Sort by: start, end, title, calendar   | start         |
| `--limit`            | `-n`  | Max events to display (0 = unlimited)  | 0             |
| `--exclude-calendar` | —     | Exclude calendars by name (repeatable) | —             |

---

## ical upcoming

Show events in the next N days. Shortcut for `ical list --from today --to "in N days"`.

```bash
ical upcoming
ical upcoming --days 14
ical upcoming --calendar Work -o json
ical next --days 3
```

| Flag                 | Short | Description                            | Default       |
| -------------------- | ----- | -------------------------------------- | ------------- |
| `--days`             | `-d`  | Number of days to look ahead           | 7             |
| `--calendar`         | `-c`  | Filter by calendar name                | All calendars |
| `--calendar-id`      | —     | Filter by calendar ID                  | —             |
| `--search`           | `-s`  | Search title, location, notes          | —             |
| `--all-day`          | —     | Show only all-day events               | false         |
| `--sort`             | —     | Sort by: start, end, title, calendar   | start         |
| `--limit`            | `-n`  | Max events to display (0 = unlimited)  | 0             |
| `--exclude-calendar` | —     | Exclude calendars by name (repeatable) | —             |

Aliases: `next`, `soon`

---

## ical show

Display full details for a single event. With no arguments, shows an interactive picker.

```bash
ical show 2                                      # Row number from last listing
ical show                                        # Interactive event picker
ical show ABC12345 -o json                       # Full or partial event ID
ical show --id "577B8983-DF44:ABC123" -o json   # Exact event ID (agents: use this)
```

| Flag     | Short | Description                                  | Default |
| -------- | ----- | -------------------------------------------- | ------- |
| `--id`   | —     | Full event ID (exact match, no prefix search) | —       |
| `--from` | `-f`  | Start date for event picker                  | Today   |
| `--to`   | `-t`  | End date for event picker                    | —       |
| `--days` | `-d`  | Number of days to show in picker             | 7       |

Event selection methods:

1. **No argument** — interactive huh picker of upcoming events
2. **Number** (e.g., `2`) — row number from the last `list`/`today`/`upcoming` output
3. **String** — full or partial event ID (positional arg)
4. **`--id`** — full event ID, exact match only (preferred for scripts/agents)

> `--id` and a positional argument are mutually exclusive — passing both is an error.

Aliases: `get`, `info`

---

## ical add

Create a new calendar event. Title can be passed as a positional argument or via `--title`.

```bash
ical add "Team standup" --start "tomorrow at 9am" --end "tomorrow at 9:30am" --calendar Work
ical add --title "Lunch" --start "today at noon" --end "today at 1pm" --location "Cafe"
ical add "Flight" --start "mar 15 at 8am" --end "mar 15 at 11am" --alert 1h --alert 1d
ical add "Weekly sync" --start "next monday at 10am" --repeat weekly --repeat-days mon
ical add -i   # Interactive mode
```

| Flag                | Short | Description                                         | Default        |
| ------------------- | ----- | --------------------------------------------------- | -------------- |
| `--title`           | `-T`  | Event title                                         | —              |
| `--start`           | `-s`  | Start date/time (required)                          | —              |
| `--end`             | `-e`  | End date/time                                       | Start + 1 hour |
| `--all-day`         | `-a`  | Create as all-day event                             | false          |
| `--calendar`        | `-c`  | Calendar name                                       | System default |
| `--location`        | `-l`  | Location string                                     | —              |
| `--notes`           | `-n`  | Notes/description                                   | —              |
| `--url`             | `-u`  | URL to attach                                       | —              |
| `--alert`           | —     | Alert before event (e.g., 15m, 1h, 1d) — repeatable | —              |
| `--repeat`          | `-r`  | Recurrence: daily, weekly, monthly, yearly          | —              |
| `--repeat-interval` | —     | Recurrence interval                                 | 1              |
| `--repeat-until`    | —     | Recurrence end date                                 | —              |
| `--repeat-count`    | —     | Number of occurrences                               | 0              |
| `--repeat-days`     | —     | Days for weekly recurrence (e.g., mon,wed,fri)      | —              |
| `--timezone`        | —     | IANA timezone (e.g., America/New_York)              | —              |
| `--interactive`     | `-i`  | Interactive mode with guided prompts                | false          |

Aliases: `create`, `new`

---

## ical update

Update an existing event. Only specified fields are changed.

```bash
ical update 2 --title "New title"
ical update 3 --start "tomorrow at 10am" --end "tomorrow at 11am"
ical update 1 --location ""              # Clear location
ical update 1 --alert none               # Clear alerts
ical update 1 --repeat none              # Remove recurrence
ical update 2 --span future --start "next monday at 9am"  # Update future occurrences
ical update -i                           # Interactive mode with picker
ical update --id "577B8983-DF44:ABC123" --title "New title"  # Exact ID (agents: use this)
```

| Flag                | Short | Description                                  | Default |
| ------------------- | ----- | -------------------------------------------- | ------- |
| `--id`              | —     | Full event ID (exact match, no prefix search) | —       |
| `--title`           | `-T`  | New title                                    | —       |
| `--start`           | `-s`  | New start date/time                          | —       |
| `--end`             | `-e`  | New end date/time                            | —       |
| `--all-day`         | `-a`  | Set all-day: "true" or "false"               | —       |
| `--calendar`        | `-c`  | Move to calendar (by name)                   | —       |
| `--location`        | `-l`  | New location (empty string to clear)         | —       |
| `--notes`           | `-n`  | New notes (empty string to clear)            | —       |
| `--url`             | `-u`  | New URL (empty string to clear)              | —       |
| `--alert`           | —     | Replace alerts (repeatable, `none` to clear) | —       |
| `--timezone`        | —     | New IANA timezone                            | —       |
| `--span`            | —     | For recurring: "this" or "future"            | this    |
| `--repeat`          | `-r`  | Set/change recurrence ("none" to remove)     | —       |
| `--repeat-interval` | —     | Change recurrence interval                   | 1       |
| `--repeat-until`    | —     | Change recurrence end date                   | —       |
| `--repeat-count`    | —     | Change recurrence count                      | 0       |
| `--repeat-days`     | —     | Change recurrence days                       | —       |
| `--interactive`     | `-i`  | Interactive mode with guided prompts         | false   |

Event selection: same as `show` (no args = picker, number = row, string = event ID, `--id` = exact).

> `--id` and a positional argument are mutually exclusive — passing both is an error.
> `update` has **no** `--force` flag and requires no confirmation — changes apply immediately.

Aliases: `edit`

---

## ical delete

Delete an event. Asks for confirmation by default.

```bash
ical delete 1 --force                              # Row number, skip confirmation
ical rm 2 --force                                  # Alias
ical delete                                        # Interactive picker
ical delete 3 --span future                        # Delete this and future occurrences
ical delete --id "577B8983-DF44:ABC123" --force   # Exact event ID (agents: use this)
```

| Flag      | Short | Description                                  | Default |
| --------- | ----- | -------------------------------------------- | ------- |
| `--id`    | —     | Full event ID (exact match, no prefix search) | —       |
| `--force` | `-f`  | Skip confirmation prompt                     | false   |
| `--span`  | —     | For recurring: "this" or "future"            | this    |
| `--from`  | —     | Start date for event picker                  | Today   |
| `--to`    | —     | End date for event picker                    | —       |
| `--days`  | `-d`  | Number of days to show in picker             | 7       |

Event selection: same as `show` (no args = picker, number = row, string = event ID, `--id` = exact).

> `--id` and a positional argument are mutually exclusive — passing both is an error.
> `update` does **not** have a `--force` flag — it applies changes immediately without confirmation.

Aliases: `rm`, `remove`

---

## ical search

Search events by title, location, and notes within a date range.

```bash
ical search "meeting"
ical search "standup" --calendar Work
ical search "dentist" --from "jan 1" --to "dec 31" --limit 5
ical find "lunch" -o json
```

| Flag         | Short | Description                 | Default       |
| ------------ | ----- | --------------------------- | ------------- |
| `--from`     | `-f`  | Start of search range       | 30 days ago   |
| `--to`       | `-t`  | End of search range         | 30 days ahead |
| `--calendar` | `-c`  | Filter by calendar name     | All calendars |
| `--limit`    | `-n`  | Max results (0 = unlimited) | 0             |

Aliases: `find`

---

## ical export

Export events to JSON, CSV, or ICS format.

```bash
ical export > events.json
ical export --format ics --output-file events.ics
ical export --calendar Work --from today --to "in 6 months" --format csv
```

| Flag            | Short | Description                     | Default       |
| --------------- | ----- | ------------------------------- | ------------- |
| `--from`        | `-f`  | Start date                      | 30 days ago   |
| `--to`          | `-t`  | End date                        | 30 days ahead |
| `--calendar`    | `-c`  | Filter by calendar name         | All calendars |
| `--format`      | —     | Format: json, csv, ics          | json          |
| `--output-file` | —     | Write to file instead of stdout | stdout        |

---

## ical import

Import events from a JSON or CSV file. Format is auto-detected from file extension.

```bash
ical import events.json
ical import events.csv --calendar "Imported"
ical import backup.json --dry-run
ical import data.json --force
```

| Flag         | Short | Description                             | Default           |
| ------------ | ----- | --------------------------------------- | ----------------- |
| `--calendar` | `-c`  | Override target calendar for all events | Original calendar |
| `--dry-run`  | —     | Preview without creating events         | false             |
| `--force`    | `-f`  | Skip confirmation prompt                | false             |

---

## ical skills

Manage AI agent skills. The ical binary embeds its own agent skill files and can install them directly into the skills directory of supported AI coding agents.

### ical skills install

Install the ical agent skill for AI coding agents. Without `--agent`, shows an interactive multi-select picker.

```bash
ical skills install                # Interactive — pick agents
ical skills install --agent claude # Direct — Claude Code only
ical skills install --agent codex  # Direct — Codex CLI only
ical skills install --agent all    # Both agents
```

| Flag      | Short | Description                          | Default     |
| --------- | ----- | ------------------------------------ | ----------- |
| `--agent` | —     | Target agent: claude, codex, or all  | Interactive |

Supported targets:
- `claude` → `~/.claude/skills/ical-cli/` (Claude Code, Copilot, Cursor, OpenCode, Augment)
- `codex` → `~/.agents/skills/ical-cli/` (Codex CLI, Copilot, Windsurf, OpenCode, Augment)

### ical skills uninstall

Remove the ical agent skill. Same `--agent` flag and interactive picker as install.

```bash
ical skills uninstall
ical skills uninstall --agent claude
```

| Flag      | Short | Description                          | Default     |
| --------- | ----- | ------------------------------------ | ----------- |
| `--agent` | —     | Target agent: claude, codex, or all  | Interactive |

### ical skills status

Show where skills are installed and whether they match the current binary version.

```bash
ical skills status
```

---

## ical version

Print version and build information. Also shows a notice if a newer version is available or if installed skills are outdated.

```bash
ical version
```

Output format: `ical <version> (commit <hash>, built <date>)`

---

## ical completion

Generate shell completion scripts.

```bash
ical completion bash > /usr/local/etc/bash_completion.d/ical
ical completion zsh > "${fpath[1]}/_ical"
ical completion fish > ~/.config/fish/completions/ical.fish
```

---

## Global Flags

These flags are available on all commands:

| Flag         | Short | Description                       | Default |
| ------------ | ----- | --------------------------------- | ------- |
| `--output`   | `-o`  | Output format: table, json, plain | table   |
| `--no-color` | —     | Disable color output              | false   |

The `NO_COLOR` environment variable is also respected.

Set `ICAL_NO_UPDATE_CHECK=1` to disable the background update check.


path: references/dates.md
content: # Natural Language Date Reference

Date flags (`--from`, `--to`, `--start`, `--end`) on ical commands accept natural language dates. All parsing is built-in with no external dependencies.

## Keywords

| Input                 | Resolves to                   |
| --------------------- | ----------------------------- |
| `today`               | Today at midnight (00:00)     |
| `tomorrow`            | Tomorrow at midnight          |
| `yesterday`           | Yesterday at midnight         |
| `now`                 | Current date and time         |
| `eod` / `end of day`  | Today at 5:00 PM              |
| `eow` / `end of week` | Next Friday at 5:00 PM        |
| `this week`           | Next Sunday at 23:59          |
| `next week`           | Next Monday at midnight       |
| `next month`          | 1st of next month at midnight |

## Relative Time

Pattern: `in <number> <unit>`

| Input                        | Example result     |
| ---------------------------- | ------------------ |
| `in 5 minutes` / `in 5 mins` | 5 minutes from now |
| `in 3 hours` / `in 3 hrs`    | 3 hours from now   |
| `in 2 days`                  | 2 days from now    |
| `in 1 week`                  | 7 days from now    |
| `in 2 months`                | 2 months from now  |

## Past References

Pattern: `<number> <unit> ago`

| Input           | Example result       |
| --------------- | -------------------- |
| `5 minutes ago` | 5 minutes before now |
| `2 hours ago`   | 2 hours before now   |
| `3 days ago`    | 3 days before now    |
| `1 week ago`    | 7 days before now    |
| `6 months ago`  | 6 months before now  |

## Weekday Patterns

| Input                | Resolves to             |
| -------------------- | ----------------------- |
| `next monday`        | Next Monday at midnight |
| `next friday at 2pm` | Next Friday at 2:00 PM  |
| `next fri 3:30pm`    | Next Friday at 3:30 PM  |
| `monday`             | Next Monday at midnight |
| `friday 2pm`         | Next Friday at 2:00 PM  |

Supports full names and 3-letter abbreviations: `sun`, `mon`, `tue`, `wed`, `thu`, `fri`, `sat`.

## Keyword + Time

| Input             | Resolves to         |
| ----------------- | ------------------- |
| `today at 5pm`    | Today at 5:00 PM    |
| `today 3:30pm`    | Today at 3:30 PM    |
| `tomorrow at 9am` | Tomorrow at 9:00 AM |
| `tomorrow 14:00`  | Tomorrow at 2:00 PM |

## Month + Day

| Input            | Resolves to             |
| ---------------- | ----------------------- |
| `mar 15`         | March 15 at midnight    |
| `march 15 2pm`   | March 15 at 2:00 PM     |
| `dec 31 11:59pm` | December 31 at 11:59 PM |

Supports full and abbreviated month names (jan/january through dec/december).

## Time Only

| Input    | Resolves to      |
| -------- | ---------------- |
| `5pm`    | Today at 5:00 PM |
| `9am`    | Today at 9:00 AM |
| `3:30pm` | Today at 3:30 PM |
| `17:00`  | Today at 5:00 PM |

## Standard Date Formats

| Format            | Example                                       |
| ----------------- | --------------------------------------------- |
| RFC 3339          | `2026-02-15T14:30:00Z`                        |
| ISO date          | `2026-02-15`                                  |
| ISO datetime      | `2026-02-15 14:30` / `2026-02-15T14:30`       |
| ISO with seconds  | `2026-02-15 14:30:00` / `2026-02-15T14:30:00` |
| 12-hour           | `2026-02-15 2:30PM`                           |
| US format         | `02/15/2026`                                  |
| US with time      | `02/15/2026 14:30` / `02/15/2026 2:30PM`      |
| Month name        | `Feb 15, 2026` / `February 15, 2026`          |
| Month name + time | `Feb 15, 2026 2:30PM` / `Feb 15, 2026 14:30`  |
| Day-first         | `15 Feb 2026` / `15 February 2026`            |

## Alert Durations

The `--alert` flag on `add` and `update` accepts duration strings:

| Input | Meaning           |
| ----- | ----------------- |
| `15m` | 15 minutes before |
| `1h`  | 1 hour before     |
| `2d`  | 2 days before     |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)