gcalcli-calendar

# gcalcli-calendar

Use `gcalcli` to read/search/manage Google Calendar with minimal tool calls and minimal output.

## Rules

### CLI flag placement (critical)
- Global flags (`--nocolor`, `--calendar`) go BEFORE the subcommand.
- Subcommand-specific flags go AFTER the subcommand name.
- Example: `gcalcli --nocolor delete --iamaexpert "query" start end` — NOT `gcalcli --nocolor --iamaexpert delete ...`.
- This applies to ALL subcommand flags: `--iamaexpert` (delete), `--noprompt`/`--allday` (add), `--use-legacy-import` (import), etc.

### Output & language
- Don't print CLI commands/flags/tool details unless the user explicitly asks (e.g. "show commands used", "/debug", "/commands").
- If asked for commands: print ALL executed commands in order (including retries) and nothing else.
- Don't mix languages within one reply.
- Be concise. No scope unless nothing found.

### Dates & formatting
- Human-friendly dates by default. ISO only if explicitly requested.
- Don't quote event titles unless needed to disambiguate.

### Calendar scope
- Trust gcalcli config (default/ignore calendars). Don't broaden scope unless user asks "across all calendars" or results are clearly wrong.

### Agenda (today-only by default)
- If user asks "agenda" without a period, return today only.
- Expand only if explicitly asked (tomorrow / next N days / date range).

### Weekday requests (no mental math)
If user says "on Monday/Tuesday/..." without a date:
1) fetch next 14 days agenda once,
2) pick matching day/event from tool output,
3) proceed (or disambiguate if multiple).

### Finding events: prefer deterministic agenda scan (meaning-first)
When locating events to cancel/delete/edit:
- Prefer `agenda` over `search`.
- Use a bounded window and match events by meaning (semantic match) rather than exact text.
- Default locate windows:
  - If user gives an exact date: scan that day only.
  - If user gives a weekday: scan next 14 days.
  - If user gives only meaning words ("train", "lecture", etc.) with no date: scan next 30 days first.
  - If still not found: expand to 180 days and say so only if still empty.

Use gcalcli `search` only as a fallback when:
- the time window would be too large to scan via agenda (token-heavy), or
- the user explicitly asked to "search".

### Search (bounded)
- Default search window: next ~180 days (unless user specified otherwise).
- If no matches: say "No matches in next ~6 months (<from>-><to>)" and offer to expand.
- Show scope only when nothing is found.

### Tool efficiency
- Default: use `--nocolor` to reduce formatting noise and tokens.
- Use `--tsv` only if you must parse/dedupe/sort.

## Actions policy (optimized for conversational speed)

This skill is designed for personal assistant use where the user expects fast, low-friction calendar management. The confirmation policy below is an intentional UX choice — see README.md for rationale and safety guards.

### Unambiguous actions: execute immediately
For cancel/delete/edit actions, skip confirmation when ALL of these hold:
- The user explicitly requested the action (e.g. "delete my dentist appointment").
- Exactly one event matches in a tight time window.
- The match is unambiguous (single clear result on an exact date, or user specified date+time).

### Ambiguous actions: always ask first
If multiple candidates match, or the match is uncertain:
- Ask a short disambiguation question listing the candidates (1-3 lines) and wait for the user's choice.

### Create events: overlap check MUST be cross-calendar (non-ignored scope)
When creating an event:
- Always run a best-effort overlap check across ALL non-ignored calendars by scanning agenda WITHOUT `--calendar`.
  - This ensures overlaps are detected even if the new event is created into a specific calendar.
- If overlap exists with busy events:
  - Ask for confirmation before creating.
- If no overlap:
  - Create immediately.

### Choose the right create method
- **`add`** — default for one-off events. Supports `--allday`, `--reminder`, `--noprompt`. Does NOT support recurrence or free/busy (transparency).
- **`import` via stdin** — use ONLY when you need recurrence (RRULE) or free/busy (TRANSP:TRANSPARENT). Pipe ICS content via stdin; NEVER write temp .ics files (working directory is unreliable in exec sandbox).
- **`quick`** — avoid unless user explicitly asks for natural-language add. Less deterministic.

### Deletes must be verified
- Use non-interactive delete with `--iamaexpert` (a `delete` subcommand flag — goes AFTER `delete`). This is gcalcli's built-in flag for non-interactive/scripted deletion.
- Always verify via agenda in the same tight window after deletion.
- If verification still shows the event, do one retry with `--refresh`.
- Never claim success unless verification confirms the event is gone.

## Canonical commands

### Agenda (deterministic listing)
- Today: `gcalcli --nocolor agenda today tomorrow`
- Next 14d (weekday resolution): `gcalcli --nocolor agenda today +14d`
- Next 30d (meaning-first locate): `gcalcli --nocolor agenda today +30d`
- Custom: `gcalcli --nocolor agenda <start> <end>`

### Search (fallback / explicit request)
- Default (~6 months): `gcalcli --nocolor search "<query>" today +180d`
- Custom: `gcalcli --nocolor search "<query>" <start> <end>`

### Create — `add` (one-off events)
- Overlap preflight (tight, cross-calendar):
  - `gcalcli --nocolor agenda <start> <end>`
  - IMPORTANT: do NOT add `--calendar` here; overlaps must be checked across all non-ignored calendars.
- Timed event:
  - `gcalcli --nocolor --calendar "<Cal>" add --noprompt --title "<Title>" --when "<Start>" --duration <minutes>`
- All-day event:
  - `gcalcli --nocolor --calendar "<Cal>" add --noprompt --allday --title "<Title>" --when "<Date>"`
- With reminders (repeatable flag):
  - `--reminder "20160 popup"` → 14 days before (20160 = 14×24×60)
  - `--reminder "10080 popup"` → 7 days before
  - `--reminder "0 popup"` → at event start
  - Time unit suffixes: `w` (weeks), `d` (days), `h` (hours), `m` (minutes). No suffix = minutes.
  - Method: `popup` (default), `email`, `sms`.

### Create — `import` via stdin (recurrence / free/busy)
Use ONLY when `add` can't cover the need (recurring events, TRANSP, etc.).
Pipe ICS directly via stdin — never write temp files.
```
echo 'BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
DTSTART;VALUE=DATE:20260308
SUMMARY:Event Title
RRULE:FREQ=YEARLY
TRANSP:TRANSPARENT
END:VEVENT
END:VCALENDAR' | gcalcli import --calendar "<Cal>"
```
- `DTSTART;VALUE=DATE:YYYYMMDD` for all-day; `DTSTART:YYYYMMDDTHHmmSS` for timed.
- `RRULE:FREQ=YEARLY` — yearly recurrence. Also: `DAILY`, `WEEKLY`, `MONTHLY`.
- `TRANSP:TRANSPARENT` — free; `TRANSP:OPAQUE` — busy (default).
- One import call = one event (one VEVENT block). For multiple events, run separate piped imports.
- Add `--reminder "TIME"` flag(s) to set reminders (overrides any VALARM in ICS).
- All import-specific flags (`--use-legacy-import`, `--verbose`, etc.) go AFTER `import`.

### Delete (with post-delete verification)
- Locate via agenda (preferred):
  - `gcalcli --nocolor agenda <dayStart> <dayEnd>` (exact date)
  - `gcalcli --nocolor agenda today +14d` (weekday)
  - `gcalcli --nocolor agenda today +30d` (meaning only)
- Delete (non-interactive, bounded):
  - `gcalcli --nocolor delete --iamaexpert "<query>" <start> <end>`
- Verify (same window):
  - `gcalcli --nocolor agenda <dayStart> <dayEnd>`
- Optional one retry if still present:
  - `gcalcli --nocolor --refresh agenda <dayStart> <dayEnd>`

### Edit / Modify existing events
- `gcalcli edit` is interactive — cannot be used in non-interactive exec.
- To change properties not editable in-place: **delete + recreate** the event.
  - Locate → delete (with `--iamaexpert`) → create with updated properties → verify.
- For bulk property changes (e.g. setting all events to free): iterate delete+recreate per event.