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

Calendar Management

Subscriptions

Access Control (ACL)

Other

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):

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, colorid, backgroundcolor, foregroundcolor, summaryoverride, 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, scopetype, scopevalue.

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,[email protected]"]

Returns busy periods for each requested calendar.

colors -- List available colors

gws calendar colors

Returns calendarcolors and eventcolors 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