gws-calendar

What this skill does

# 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:
```bash
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 [email protected] --role reader` |
| Remove access | `gws calendar unshare --rule-id "user:[email protected]"` |
| Update access | `gws calendar update-acl --rule-id "user:[email protected]" --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

```bash
gws calendar list
```

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

### events -- List events

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

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

### rsvp -- Respond to an event invitation

```bash
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

```bash
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

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

### get-calendar -- Get calendar metadata

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

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

### create-calendar -- Create a secondary calendar

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

### update-calendar -- Update a calendar

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