Google Calendar CLI

manage google calendar events via porteden cli. use for listing, searching, reading events. mutation ops (create, update, delete, respond) require explicit user confirmation before execution.

intent

this skill lets you query and manipulate google calendar events through the porteden cli. read operations (list, search, get single event, check free/busy) run immediately. write operations (create, update, delete, respond to invites) block until you confirm the target account, calendar id, event details, and the exact change you're making. use this when you need to sync, audit, or modify google calendar state without risking accidental notifications to attendees or data loss.

inputs

required:

• porteden cli installed: brew install porteden/tap/porteden or go install github.com/porteden/cli/cmd/porteden@latest
• google account access (browser login or api key token)

authentication (choose one, in order of preference):

• browser login via porteden auth login - opens oauth flow, stores credentials in system keyring (recommended, most secure)
• api key token via porteden auth login --token <key> - stores in system keyring
• environment variable PE_API_KEY - used automatically if set, no login needed

optional inputs:

• PE_PROFILE env var or --profile flag - isolates which google account to use (default: primary)
• PE_TIMEZONE env var - controls time display (default: utc)
• PE_FORMAT, PE_COLOR, PE_VERBOSE env vars - output formatting

external connections:

• google calendar api (https://www.googleapis.com/calendar)
• system keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager)
• google account security page (accounts.google.com/security) for token revocation

procedure

setup (one-time):

1. run porteden auth login and complete browser oauth flow with your google account. credentials are stored in system keyring automatically.
2. verify auth worked: run porteden auth status and confirm your account email appears.
3. (optional) set export PE_PROFILE=work in your shell to avoid repeating --profile on every command.

read operations:

1. list all calendars in the active account: porteden calendar calendars -jc
2. capture the calendar id (integer, e.g. 724) from the output. note the externalId field if you need the google email format.
3. query events by time range:
   • today: porteden calendar events --today -jc
   • tomorrow: porteden calendar events --tomorrow -jc
   • custom range: porteden calendar events --from 2026-02-01 --to 2026-02-07 -jc
   • next n days: porteden calendar events --days 7 -jc
   • entire week: porteden calendar events --week -jc
4. narrow results with filters:
   • search by keyword: porteden calendar events -q "meeting" --today -jc
   • by attendee email: porteden calendar events --week --attendees "alice@example.com,bob@example.com" -jc
   • by contact: porteden calendar by-contact "user@example.com" -jc or --name "John" (matches display name, falls back to email local-part)
   • include cancelled events: add --include-cancelled
5. fetch single event details: porteden calendar event <eventId> -jc
6. check free/busy slots: porteden calendar freebusy --week -jc or --calendars 123,456 for specific calendars.
7. add -jc (json compact) to all read commands for cleaner, ai-friendly output.
8. if results span multiple pages, use --all to fetch all pages automatically, or --limit 100 --offset 0 then increment offset manually.
9. output contains meta block with count, totalCount, hasMore, limit, offset, from, to. check hasMore to know if pagination is needed.

write operations (create):

1. output the intended calendar id, event summary, start/end times, attendees, and recurrence (if any) and wait for user confirmation.
2. on confirmation, run the command:
   • simple event: porteden calendar create --calendar <id> --summary "Meeting" --from "2026-02-01T10:00:00Z" --to "2026-02-01T11:00:00Z" --location "Room A" --attendees "a@b.com,c@d.com"
   • all-day event: porteden calendar create --calendar <id> --summary "Holiday" --from "2026-07-04T00:00:00Z" --to "2026-07-05T00:00:00Z" --all-day
   • recurring event: porteden calendar create --calendar <id> --summary "Standup" --from "2026-02-01T09:00:00Z" --to "2026-02-01T09:30:00Z" --recurrence "RRULE:FREQ=WEEKLY;COUNT=10"
3. output contains event id, status (confirmed), and attendee list. confirm successful creation.

write operations (update):

1. output the event id, current state (summary, time, attendees), the field(s) being changed, and attendees list if it changes, then wait for user confirmation.
2. on confirmation, run:
   • change title or time: porteden calendar update <eventId> --summary "New Title" --from "2026-02-01T14:00:00Z"
   • add attendees: porteden calendar update <eventId> --add-attendees "new@example.com" (by default sends notifications to all attendees, use --notify=false to suppress)
   • remove attendees: porteden calendar update <eventId> --remove-attendees "old@example.com" (notifications sent by default)
3. output contains updated event details. confirm the change.

write operations (delete):

1. output the event id, summary, time, organizer, and full attendee list, then wait for user confirmation.
2. on confirmation, run: porteden calendar delete <eventId> (by default sends cancellation emails to all attendees; add --no-notify to suppress)
3. event is removed. confirm deletion.

write operations (respond to invite):

1. output the event id, summary, time, organizer, and your current response status, then wait for user confirmation of the new response (accepted, tentative, or declined).
2. on confirmation, run: porteden calendar respond <eventId> accepted (or tentative or declined)
3. output contains your new response status. confirm the rsvp.

decision points

if porteden is not installed: prompt the user to install via brew install porteden/tap/porteden (macOS preferred) or go install github.com/porteden/cli/cmd/porteden@latest (any platform). do not proceed until installation is verified.

if PE_API_KEY env var is set: use it automatically for auth. do not prompt for browser login unless the token is invalid (401 or 403).

if PE_API_KEY is not set and no keyring entry exists: run porteden auth login to open the browser oauth flow. do not fall back to manual credential entry.

if the user is the organizer of an event: respond returns 409 CANNOT_RSVP_AS_ORGANIZER. surface this error message to the user. this is not retryable; organizers do not rsvp to their own events.

if the user is not in the attendee list of an event: respond returns 409 NOT_AN_ATTENDEE. surface this message to the user. this is not retryable.

if a write operation (create, update, delete, respond) lacks explicit user confirmation: do not execute the command. echo back the details and wait for an affirmative response before proceeding.

if a create, update, or delete command targets the wrong calendar (e.g. wrong profile or calendar id): halt and ask the user to confirm the calendar id via porteden calendar calendars -jc before retrying.

if a query returns no results (empty event list): output "no events found" with the query params (date range, filters, etc.). do not treat this as an error.

if a query hits rate limit (429 RATE_LIMITED): wait 30-60 seconds and retry automatically. the response headers carry x-monthly-limit, x-monthly-used, x-monthly-remaining.

if a query hits quota limit (429 QUOTA_EXCEEDED): surface the error to the user. quota-blocked requests do not consume quota. the user must wait for the next month or contact google support. do not retry automatically.

if network timeout or connection error occurs: retry up to 3 times with exponential backoff (1s, 2s, 4s). if all retries fail, surface the error and suggest checking internet connectivity.

if auth token expires: the cli will return 401. prompt the user to run porteden auth login again to refresh credentials.

if the user wants to revoke access (e.g. after a task completes on a shared machine): run porteden auth logout to clear the keyring entry, then visit accounts.google.com, go to Security, find "Third-party access", and revoke porteden/clawhub.

output contract

read operations: all output in json format with -jc (compact, ai-optimized).

• events list: array of objects with keys: id, summary, startUtc, endUtc, durationMinutes, allDay, status, organizer, attendees[] (with email, displayName, response), joinUrl, meta (with pagination info).
• calendars list: array of objects with keys: id (integer), summary, externalId (google email), primary (boolean).
• free/busy: object with keys: calendars (object mapping calendar id to busy slots), timeMin, timeMax.
• single event: single event object (same schema as list).
• by-contact: array of events where the specified contact appears in attendees.

write operations (create, update): single event object with id, summary, startUtc, endUtc, status, attendees[], and confirmation that the operation succeeded.

write operations (delete): confirmation message (no event object returned).

write operations (respond): single event object with your updated response status in the attendees array.

all output: times in rfc3339 utc format (e.g. 2026-02-01T10:00:00Z). all-day events flagged with allDay: true and duration of 1440 minutes (24 hours).

outcome signal

• read operations: output displays the queried events or calendars with no errors. user can see summaries, times, attendees, and response statuses. pagination info confirms whether more results exist.
• write operations (create): new event appears in the calendar. output shows the event id, summary, and confirmed status. user can verify in google calendar or via porteden calendar event <id> -jc.
• write operations (update): event details change (title, time, attendees). output shows updated fields. notifications are sent to attendees unless suppressed with --notify=false.
• write operations (delete): event is removed from the calendar. output confirms deletion. cancellation emails are sent to attendees unless suppressed with --no-notify.
• write operations (respond): your rsvp status changes (accepted, tentative, declined). output shows your new response in the attendees array. organizer receives a notification of your response.
• auth operations: porteden auth status shows your google account email. porteden auth logout clears keyring entry and outputs confirmation.
• error cases: rate limit returns retryable message; quota limit returns non-retryable message; 401 auth failure prompts re-login; 409 precondition errors (organizer/not attendee) surface the message without retry.