## Overview

Every flag that accepts a date (`--from`, `--to`, `--start`, `--end`, `--repeat-until`) supports natural language input. The parser is provided by the shared [`go-eventkit/dateparser`](https://github.com/BRO3886/go-eventkit) package, which handles 20+ patterns and is battle-tested across both ical and [rem](https://github.com/BRO3886/rem).

All relative expressions are evaluated at the moment the command runs.

## Supported Patterns

### Relative Days

| Input        | Resolves to              |
|--------------|--------------------------|
| `today`      | Start of today           |
| `tomorrow`   | Start of tomorrow        |
| `yesterday`  | Start of yesterday       |

### Weekdays

| Input           | Resolves to                        |
|-----------------|-------------------------------------|
| `next monday`   | Next occurrence of that weekday    |
| `next friday`   | Next occurrence of that weekday    |
| `friday`        | Next Friday (same as `next friday`) |

### Relative Periods

| Input         | Resolves to                      |
|---------------|----------------------------------|
| `next week`   | Monday of next week              |
| `next month`  | 1st of next month                |
| `this week`   | End of this week (Sunday 11:59 PM) |

### Relative Time

| Input              | Resolves to                |
|--------------------|----------------------------|
| `in 3 hours`       | 3 hours from now           |
| `in 30 minutes`    | 30 minutes from now        |
| `in 5 days`        | 5 days from now            |
| `in 2 weeks`       | 14 days from now           |
| `in 1 month`       | 1 month from now           |

### Past Relative

| Input             | Resolves to               |
|-------------------|---------------------------|
| `2 hours ago`     | 2 hours before now        |
| `5 days ago`      | 5 days before now         |
| `1 month ago`     | 1 month before now        |

### Time of Day

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

### Weekday + Time

| Input           | Resolves to                |
|-----------------|----------------------------|
| `friday 2pm`    | Next Friday at 2:00 PM     |
| `monday 9am`    | Next Monday at 9:00 AM     |

### Month + Day

Both month-first and day-first ordering are supported:

| Input             | Resolves to                  |
|-------------------|------------------------------|
| `mar 15`          | March 15 of this year        |
| `march 15`        | March 15 of this year        |
| `dec 25`          | December 25 of this year     |
| `21 mar`          | March 21 of this year        |
| `21 march 2pm`    | March 21 at 2:00 PM          |
| `21 march 2026`   | March 21, 2026               |

### ISO 8601

| Input                | Resolves to             |
|----------------------|-------------------------|
| `2026-03-15`         | March 15, 2026          |
| `2026-03-15 14:00`   | March 15, 2026 at 2 PM |

### Shorthand Keywords

| Input  | Resolves to              |
|--------|--------------------------|
| `eod`  | Today at 5:00 PM         |
| `eow`  | Friday at 5:00 PM        |

## Timezone Handling

Timezone abbreviations like `CDT`, `EST`, or `PST` **cannot** be embedded in date strings — the parser will reject them. To create events in a different timezone, use the `--timezone` flag with an IANA timezone name:

```bash
# This will fail
ical add "Meeting" --start "2026-06-17 at 2pm CDT"

# Use --timezone instead
ical add "Meeting" --start "2026-06-17 14:00" --timezone "America/Chicago"
```

The `--timezone` flag accepts any IANA name (e.g., `America/Chicago`, `America/New_York`, `Europe/Madrid`). Events are stored with the correct timezone and displayed in your local timezone.

## End-of-Day Behavior

When a date is used with the `--to` flag and resolves to midnight (00:00:00), ical automatically bumps it to 23:59:59 of that day. This ensures that `--to "feb 12"` includes all events on February 12, not just those before midnight.

This applies to `list`, `search`, `export`, and the interactive event picker.

## Usage Examples

```bash
# Events from today through end of next Friday
ical list -f today -t "next friday"

# Events in the past month
ical list -f "1 month ago" -t today

# Create event starting in 2 hours
ical add "Quick call" -s "in 2 hours" -e "in 3 hours"

# Search events around a specific date
ical search "review" -f "mar 1" -t "mar 31"

# Export this week's events
ical export -f today -t "this week" --format json
```