gws-calendar

name	gws-calendar
version	2.0.0
description	Google Calendar CLI operations via gws. Use when users need to list calendars, view events, create/update/delete events, RSVP to invitations, manage calendar CRUD, subscriptions, ACL, free/busy queries, colors, and settings. Triggers: calendar, events, meetings, schedule, rsvp, invite, share, freebusy.
metadata	{"short-description":"Google Calendar CLI operations","compatibility":"claude-code, codex-cli"}

Google Calendar (gws calendar)

gws calendar provides CLI access to Google Calendar with structured JSON output.

Disclaimer: gws is not the official Google CLI. This is an independent, open-source project not endorsed by or affiliated with Google.

Dependency Check

Before executing any gws command, verify the CLI is installed:

gws version

If not found, install: go install github.com/omriariav/workspace-cli/cmd/gws@latest

Authentication

Requires OAuth2 credentials. Run gws auth status to check. If not authenticated: gws auth login (opens browser for OAuth consent). For initial setup, see the gws-auth skill.

Quick Command Reference

Events

Task	Command
List calendars	gws calendar list
View upcoming events	gws calendar events
View next 14 days	gws calendar events --days 14
3-day window (yesterday–tomorrow)	gws calendar events --from "2026-03-24" --days 3
Search events by text	gws calendar events --query "standup"
View pending invites	gws calendar events --days 30 --pending
Filter by event type	gws calendar events --event-types focusTime,outOfOffice
Get event by ID	gws calendar get --id <event-id>
Create an event	gws calendar create --title "Meeting" --start "2024-02-01 14:00" --end "2024-02-01 15:00"
Quick add from text	gws calendar quick-add --text "Lunch with John tomorrow at noon"
Update an event	gws calendar update <event-id> --title "New Title"
Delete an event	gws calendar delete <event-id>
RSVP to an event	gws calendar rsvp <event-id> --response accepted
List recurring instances	gws calendar instances --id <event-id>
Move event to calendar	gws calendar move --id <event-id> --destination <cal-id>

Calendar Management

Task	Command
Get calendar metadata	gws calendar get-calendar --id <cal-id>
Create secondary calendar	gws calendar create-calendar --summary "Projects"
Update calendar	gws calendar update-calendar --id <cal-id> --summary "New Name"
Delete secondary calendar	gws calendar delete-calendar --id <cal-id>
Clear all events	gws calendar clear

Subscriptions

Task	Command
Subscribe to calendar	gws calendar subscribe --id <cal-id>
Unsubscribe	gws calendar unsubscribe --id <cal-id>
Get subscription info	gws calendar calendar-info --id <cal-id>
Update subscription	gws calendar update-subscription --id <cal-id> --color-id 7

Access Control (ACL)

Task	Command
List ACL rules	gws calendar acl
Share with user	gws calendar share --email [e-mail] --role reader
Remove access	gws calendar unshare --rule-id "user:[e-mail]"
Update access	gws calendar update-acl --rule-id "user:[e-mail]" --role writer

Other

Task	Command
Query free/busy	gws calendar freebusy --from "2024-03-01 09:00" --to "2024-03-01 17:00"
List colors	gws calendar colors
List settings	gws calendar settings

Detailed Usage

list -- List calendars

gws calendar list

Lists all calendars you have access to, including shared calendars and subscriptions.

events -- List events

gws calendar events [flags]

Lists upcoming events from a calendar.

Flags:

• --calendar-id string -- Calendar ID (default: "primary")
• --days int -- Number of days to look ahead (default 7)
• --from string -- Start date (YYYY-MM-DD or RFC3339); defaults to now. Enables fetching past events.
• --max int -- Maximum number of events (default 50)
• --pending -- Only show events with pending RSVP (needsAction). Tip: increase --max when using --pending over long date ranges, since --max limits the API fetch before client-side filtering.
• --query string -- Free-text search across summary, description, location, and attendees
• --event-types strings -- Filter by event type: default, birthday, focusTime, fromGmail, outOfOffice, workingLocation
• --show-deleted -- Include cancelled/deleted events in results
• --timezone string -- Timezone for response times (e.g. America/New_York)
• --updated-min string -- Only events modified after this time (RFC3339)

Output includes (fields omitted when empty):

Category	Fields
Core	id, summary, status
Time	start, end, all_day
Details	description, location, hangout_link, html_link, created, updated, color_id, visibility, transparency, event_type
People	organizer (email), creator (email), response_status (your RSVP)
Attendees	attendees[] -- { email, response_status, optional, organizer, self }
Conference	conference -- { conference_id, solution, entry_points[]: { type, uri } }
Attachments	attachments[] -- { file_url, title, mime_type, file_id }
Recurrence	recurrence[] -- RRULE strings
Reminders	reminders -- { use_default, overrides[]: { method, minutes } }

get -- Get event by ID

gws calendar get --id <event-id> [--calendar-id <cal-id>]

Returns full event details using mapEventToOutput format (same fields as events).

create -- Create an event

gws calendar create --title <title> --start <time> --end <time> [flags]

Flags:

• --title string -- Event title (required)
• --start string -- Start time in RFC3339 or YYYY-MM-DD HH:MM format (required)
• --end string -- End time in RFC3339 or YYYY-MM-DD HH:MM format (required)
• --calendar-id string -- Calendar ID (default: "primary")
• --description string -- Event description
• --location string -- Event location
• --attendees strings -- Attendee email addresses
• --add-self bool (default true) -- Add the authenticated user as an accepted attendee. Pass --add-self=false to opt out.

quick-add -- Quick add from text

gws calendar quick-add --text "Lunch with John tomorrow at noon" [--calendar-id <cal-id>]

Uses Google's natural language processing to create an event from a text string.

update -- Update an event

gws calendar update <event-id> [flags]

Updates an existing calendar event. Uses PATCH (only changed fields are sent).

Flags:

• --title string -- New event title
• --start string -- New start time
• --end string -- New end time
• --description string -- New event description
• --location string -- New event location
• --add-attendees strings -- Attendee emails to add
• --calendar-id string -- Calendar ID (default: "primary")

delete -- Delete an event

gws calendar delete <event-id> [--calendar-id <cal-id>]

rsvp -- Respond to an event invitation

gws calendar rsvp <event-id> --response <status> [--message <text>] [--calendar-id <cal-id>]

Valid responses: accepted, declined, tentative. If --message is provided, notifies all attendees.

instances -- List recurring event instances

gws calendar instances --id <event-id> [--max 50] [--from <time>] [--to <time>] [--calendar-id <cal-id>]

Lists all instances of a recurring event within an optional time range.

move -- Move event to another calendar

gws calendar move --id <event-id> --destination <cal-id> [--calendar-id <cal-id>]

get-calendar -- Get calendar metadata

gws calendar get-calendar --id <cal-id>

Returns: id, summary, description, timezone, location, etag.

create-calendar -- Create a secondary calendar

gws calendar create-calendar --summary <name> [--description <text>] [--timezone <tz>]

update-calendar -- Update a calendar

gws calendar update-calendar --id <cal-id> [--summary <name>] [--description <text>] [--timezone <tz>]

delete-calendar -- Delete a secondary calendar

gws calendar delete-calendar --id <cal-id>

clear -- Clear all events from a calendar

gws calendar clear [--calendar-id <cal-id>]

subscribe -- Subscribe to a public calendar

gws calendar subscribe --id <cal-id>

unsubscribe -- Unsubscribe from a calendar

gws calendar unsubscribe --id <cal-id>

calendar-info -- Get subscription info

gws calendar calendar-info --id <cal-id>

Returns: id, summary, primary, description, timezone, color_id, background_color, foreground_color, summary_override, hidden, selected, access_role.

update-subscription -- Update subscription settings

gws calendar update-subscription --id <cal-id> [--color-id <id>] [--hidden] [--summary-override <name>]

acl -- List access control rules

gws calendar acl [--calendar-id <cal-id>]

Returns array of rules with: id, role, scope_type, scope_value.

share -- Share calendar with a user

gws calendar share --email <email> --role <role> [--calendar-id <cal-id>]

Valid roles: reader, writer, owner, freeBusyReader.

unshare -- Remove calendar access

gws calendar unshare --rule-id <rule-id> [--calendar-id <cal-id>]

update-acl -- Update access control rule

gws calendar update-acl --rule-id <rule-id> --role <role> [--calendar-id <cal-id>]

freebusy -- Query free/busy information

gws calendar freebusy --from <time> --to <time> [--calendars "primary,[e-mail]"]

Returns busy periods for each requested calendar.

colors -- List available colors

gws calendar colors

Returns calendar_colors and event_colors maps with background/foreground hex values.

settings -- List user calendar settings

gws calendar settings

Returns all user calendar settings as key-value pairs.

Output Modes

gws calendar events --format json    # Structured JSON (default)
gws calendar events --format yaml    # YAML format
gws calendar events --format text    # Human-readable text

Tips for AI Agents

• Always use --format json (the default) for programmatic parsing
• Use gws calendar events to get event IDs, then use those IDs for update/delete/rsvp/get/move
• Time format accepts both RFC3339 (2024-02-01T14:00:00Z) and human-friendly (2024-02-01 14:00)
• The update command uses PATCH (not PUT), so only changed fields are sent
• For non-primary calendars, get the calendar ID from gws calendar list first
• Use quick-add for natural language event creation (e.g. "Meeting with Bob next Tuesday 2pm")
• Use freebusy to check availability before creating events
• ACL roles: freeBusyReader < reader < writer < owner
• Default event window is 7 days; increase with --days for broader views