# Google Workspace CLI (gws)

One CLI over every Google Workspace API, with JSON output and agent skills for Calendar events, free/busy and agendas.

gws is a Rust CLI on the googleworkspace GitHub org that builds its command surface from Google's Discovery Service at runtime, so every Calendar v3 method (events, calendars, ACL, free/busy, settings) is a shell command with structured JSON output. It ships 100+ agent skills, a Gemini CLI extension and helper commands such as calendar +agenda and +insert. Google Calendar itself is free with a Google account.

- Capabilities: operable
- Vertical: scheduling-staffing
- Shape: product
- Form factor: cli
- Execution model: deterministic
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/googleworkspace/cli (Apache-2.0), 30708 stars, last commit 2026-08-25
- Last activity: 2026-08-25
- Page: apps/googleworkspace--cli.html
- JSON: apps/googleworkspace--cli.json

## Use it when

- my whole calendar lives in Google and I want my agent to find a slot, book it and send invites from the terminal
- I need scripted Calendar operations in CI or on a server with a service account and no browser

## Gotchas

- README: 'not an officially supported Google product' and breaking changes expected before v1.0
- Unverified OAuth apps are capped at about 25 scopes, so log in with -s calendar rather than the recommended preset; you must add yourself as a test user
- gws auth setup requires the gcloud CLI; otherwise create the OAuth client by hand
- Google Workspace business plans are paid, but a free Google account is enough for Calendar

## Editions

- Free: Free, open source
  - source: https://github.com/googleworkspace/cli
  - binary: https://github.com/googleworkspace/cli/releases
  - installable: npm install -g @googleworkspace/cli
  - installable: brew install googleworkspace-cli

## Operable: what an agent can drive

Operability: official. Interface: cli at https://github.com/googleworkspace/cli (published by the builder, local).

### Reach (partial coverage)

- List, create, update and delete events: reachable. skills/gws-calendar/SKILL.md: events list, insert, patch, update, delete
- Query free/busy across calendars: reachable. SKILL.md: freebusy query; recipe-find-free-time skill
- Show an agenda across all calendars: reachable. helper command gws calendar +agenda with timezone handling
- Create an event from a text phrase: reachable. SKILL.md: events quickAdd
- Manage calendars and sharing: reachable. SKILL.md: calendars insert/patch/delete, calendarList, acl insert/list
- Expand recurring events: reachable. SKILL.md: events instances
- Watch for changes: reachable. SKILL.md: events watch and channels stop; needs a public HTTPS endpoint to receive pushes
- Reschedule and invite in bulk: reachable. skills recipe-reschedule-meeting, recipe-batch-invite-to-event, recipe-create-events-from-sheet
- Appointment schedules (booking pages): not reachable. not in the Calendar v3 Discovery surface, so not in gws
- Attach a Google Meet link: undetermined. conferenceData on events insert; gws-meet skill exists but not verified for calendar events

## Code stack

- Languages: Rust
- Frameworks: none
- Package manager: cargo
- Database: none
- Hosting target: binary

## Model stack

- Providers: any agent that can run a shell
- Models: none
- Keys you need (names only): none
- Prompts live in: skills/gws-calendar/SKILL.md, skills/gws-calendar-agenda/SKILL.md, skills/gws-calendar-insert/SKILL.md, skills/recipe-find-free-time, skills/recipe-reschedule-meeting, skills/recipe-plan-weekly-schedule
- Tools: gws calendar events, gws calendar freebusy query, gws calendar +agenda, gws calendar +insert

## Skills

bundled: Ships per-service skills (Drive, Gmail, Calendar, Docs, Chat, Admin) that teach an agent to drive the CLI; installable individually or as a set.
- Paths: skills/gws-*/SKILL.md
- Install: npx skills add https://github.com/googleworkspace/cli

## Evidence and confidence

- formFactor: README: CLI binary from GitHub Releases, npm or Homebrew (confidence 0.95)
- executionModel: the CLI makes API calls; no model at runtime (Model Armor sanitization is optional and external) (confidence 0.9)
- operability: published on the googleworkspace GitHub organization; Calendar helper commands and skills in the repo (confidence 0.85)
- editions: README: Apache-2.0 source, binaries, npm, brew, nix (confidence 0.95)
- active: shortlist pushedAt 2026-08-25
- reach:  (confidence 0.85)

## Open questions

- Official by organization but disclaimed as unsupported: does the Curator treat googleworkspace-org publication as official?
- Provenance: CLAUDE.md and AGENTS.md sit at the repo root; how much of the code is agent-written is not stated

## Sources

- https://github.com/googleworkspace/cli (sourcing:scheduling-staffing:vendor)
- https://github.com/googleworkspace/cli/blob/main/skills/gws-calendar/SKILL.md (analysis:scheduling-staffing)