google-calendar

# Google Calendar + Tasks Access

## Quick start

- Create a Google Cloud OAuth client (Desktop app) and save the credentials JSON to `~/.config/google-calendar/credentials.json`.
- Install dependencies (venv recommended):
  ```bash
  python3 -m venv ~/.config/google-calendar/venv
  ~/.config/google-calendar/venv/bin/pip install -r <skill_dir>/scripts/requirements.txt
  ```
- Authenticate and store a token:
  - Calendar only:
    - `<skill_dir>/scripts/gcal-auth`
  - Tasks only:
    - `<skill_dir>/scripts/gcal-auth --scopes https://www.googleapis.com/auth/tasks`
  - Calendar + Tasks (single token):
    - `<skill_dir>/scripts/gcal-auth --scopes https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/tasks`
- Call the API:
  - `<skill_dir>/scripts/gcal list-calendars`

## Credentials and tokens

- Credentials are expected at `~/.config/google-calendar/credentials.json` by default.
- Tokens are stored at `~/.config/google-calendar/token.json` by default.
- Use `--token` or `GCAL_TOKEN_PATH` to switch accounts or isolate environments.

## Date/time rules

- Use RFC3339 for timed events (e.g., `2026-01-22T10:00:00-08:00`).
- Use `YYYY-MM-DD` for all-day events and set `end` to the next day (exclusive).
- Set `--time-zone` when the datetime has no offset.

## Common commands

- List calendars:
  - `<skill_dir>/scripts/gcal list-calendars`
- List events:
  - `<skill_dir>/scripts/gcal list-events --calendar-id primary --time-min 2026-01-22T00:00:00-08:00 --time-max 2026-01-22T23:59:59-08:00`
- Search events:
  - `<skill_dir>/scripts/gcal list-events --calendar-id primary --q "standup" --time-min ... --time-max ...`
- Create event (simple):
  - `<skill_dir>/scripts/gcal create-event --calendar-id primary --summary "Review" --start 2026-01-22T10:00:00-08:00 --end 2026-01-22T11:00:00-08:00`
- Update event (simple):
  - `<skill_dir>/scripts/gcal update-event --calendar-id primary --event-id <id> --summary "New title"`
- Delete event:
  - `<skill_dir>/scripts/gc