---
name: "Google Workspace"
description: Work with Gmail, Drive, Docs, Sheets, Calendar, and Chat through the `gws` CLI.
version: 1
situations: gmail, google drive, google docs, sheets, google calendar, workspace
requires-secrets:
requires-packages:
requires-connector: google-workspace
---

# Google Workspace (`gws`)

Runs through the Google Workspace CLI in your **bash** tool. The operator connected it from 00's skill
store, which also created the Google Cloud project and OAuth client behind it.

Two things to know before you lean on this:

- `gws` is **published by Google but not an officially supported product**, and it is pre-1.0. If a
  command shape has changed under you, say so and check `gws <service> --help` rather than guessing.
- The connected app only holds the scopes granted at setup (Drive, Gmail, Docs, Sheets, Calendar). A
  403 usually means a missing scope, not a missing file — report that instead of retrying.

## First, know who you are

```
gws drive files list --params '{"pageSize":1}'
```

An error here means the operator needs **Skill store → Google Workspace → Connect** (and, on an
unverified consent screen, to add themselves as a test user).

Commands are generated from Google's API discovery documents, so they mirror the REST API exactly:
`gws <service> <resource> <method> --params '<JSON>'`. Helper shortcuts are prefixed with `+`.

## Gmail

```
gws gmail messages list --params '{"q":"is:unread newer_than:7d","maxResults":20}'
gws gmail messages get --params '{"id":"MESSAGE_ID","format":"full"}'
gws gmail threads get --params '{"id":"THREAD_ID"}'
gws gmail +send --to someone@example.com --subject "…" --body "…"
```

**Sending mail is irreversible and it goes out under the operator's name.** Draft it, show the full
text and every recipient, and wait for an explicit yes in this turn. Never send to a list you
assembled yourself from a search.

## Drive, Docs, Sheets

```
gws drive files list --params '{"q":"name contains '\''report'\''","fields":"files(id,name,mimeType,modifiedTime)"}'
gws drive files get --params '{"fileId":"…","alt":"media"}' > local-copy.pdf
gws docs documents get --params '{"documentId":"…"}'
gws sheets spreadsheets.values get --params '{"spreadsheetId":"…","range":"Sheet1!A1:F50"}'
gws sheets spreadsheets.values update --params '{"spreadsheetId":"…","range":"Sheet1!A1","valueInputOption":"USER_ENTERED"}' --data '{"values":[["…"]]}'
```

Writing to a spreadsheet overwrites cells with no undo for the person watching it. Name the sheet and
the range first.

## Calendar

```
gws calendar +agenda
gws calendar events list --params '{"calendarId":"primary","timeMin":"2026-08-14T00:00:00Z","singleEvents":true,"orderBy":"startTime"}'
gws calendar events insert --params '{"calendarId":"primary"}' --data '{"summary":"…","start":{"dateTime":"…"},"end":{"dateTime":"…"}}'
```

Creating an event with attendees sends invitations to real people. Show the guest list first.

## Never without being asked in this turn

Sending mail, inviting attendees, deleting or trashing Drive files, changing sharing permissions
(`drive permissions create` grants real access to real people), emptying trash, or editing a document
the operator did not name.