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): 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/gcal delete-event --calendar-id primary --event-id <id>

• Free/busy:

• <skill_dir>/scripts/gcal freebusy --calendars primary,team@company.com --time-min ... --time-max ...

• List task lists:

• <skill_dir>/scripts/gcal list-tasklists

• List tasks:

• <skill_dir>/scripts/gcal list-tasks --tasklist <tasklist_id>

• Create task:

• <skill_dir>/scripts/gcal create-task --tasklist <tasklist_id> --title "Buy milk" --due 2026-01-22T10:00:00-08:00

• Update task:

• <skill_dir>/scripts/gcal update-task --tasklist <tasklist_id> --task-id <id> --notes "Bring receipt"

• Delete task:

• <skill_dir>/scripts/gcal delete-task --tasklist <tasklist_id> --task-id <id>

Advanced usage

• Use call to hit any Calendar API endpoint:

• <skill_dir>/scripts/gcal call GET /users/me/calendarList

• <skill_dir>/scripts/gcal call POST /calendars/primary/events --body-file /path/to/event.json

• Use --body-file or --body (JSON string) for complex payloads (attendees, recurrence, conferenceData).

• Run multiple accounts by using different token files with --token .

Safety

• Confirm intent before creating, updating, or deleting events.

• Keep OAuth credentials and token files out of git.