# Google Workspace

> Drives Gmail, Calendar, Drive, Docs, Sheets, and Contacts through the gws CLI or the bundled Python OAuth wrapper (setup.py / google_api.py). Use when the user wants to search or send mail, manage events, upload or share Drive files, or edit Sheets/Docs. Not for email-only Gmail App Password setups (prefer himalaya). Do not use for Microsoft 365 or local Obsidian notes.

- Skill: `gabrielmoreira/google-workspace-2` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/google-workspace-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/google-workspace-2/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gabrielmoreira/google-workspace-2

---


# Google Workspace

Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OAuth and a thin CLI wrapper. When `gws` is installed, the skill uses it as the execution backend for broader Google Workspace coverage; otherwise it falls back to the bundled Python client implementation.

## When to Use

- User asks to **search, read, send, or reply to Gmail** messages.
- User asks to **list, create, or delete Calendar events**.
- User asks to **search, upload, download, share, or delete Drive files**.
- User asks to **read, create, or append to Google Sheets or Docs**.
- User asks to **list Google Contacts**.
- User mentions keywords: Gmail, Google Calendar, Google Drive, Google Sheets, Google Docs, Google Contacts, Workspace.

If the user needs **email only** and has not already set up this skill, prefer the `himalaya` skill (Gmail App Password, 2-minute setup, no Google Cloud project). Load the himalaya skill and follow its setup instructions.

## Prerequisites

- Python 3.8+ installed and on PATH.
- A Google Cloud OAuth Desktop client (`google_client_secret.json`).
- Required APIs enabled in Google Cloud Console: Gmail API, Google Calendar API, Google Drive API, Google Sheets API, Google Docs API, People API.
- On Windows (PowerShell), use the same commands but adjust path separators. The scripts are Python and cross-platform; `$GSETUP` / `$GAPI` shorthands use bash syntax — on PowerShell define them as:
  ```powershell
  $GSETUP = "python $env:HERMES_HOME\skills\productivity\google-workspace\scripts\setup.py"
  $GAPI   = "python $env:HERMES_HOME\skills\productivity\google-workspace\scripts\google_api.py"
  ```
  If `HERMES_HOME` is unset, default to `$HOME/.hermes` (bash) or `$env:USERPROFILE\.hermes` (PowerShell).

## References

- `references/gmail-search-syntax.md` — Gmail search operators (`is:unread`, `from:`, `newer_than:`, `has:attachment`, etc.). **Load this file** with `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")` whenever the user asks for a complex Gmail search or you are unsure of the correct operator syntax.

## Scripts

- `scripts/setup.py` — OAuth2 setup (run once to authorize). Also handles `--check`, `--revoke`, `--install-deps`.
- `scripts/google_api.py` — compatibility wrapper CLI. Prefers `gws` for operations when available, while preserving Hermes' existing JSON output contract.

## Procedure

### First-Time Setup

The setup is fully non-interactive — you drive it step by step so it works on CLI, Telegram, Discord, or any platform.

Define a shorthand first:

```bash
GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"
```

#### Step 0: Check if already set up

```bash
$GSETUP --check
```

If it prints `AUTHENTICATED`, skip to Usage — setup is already done.

#### Step 1: Triage — ask the user what they need

Before starting OAuth setup, ask the user TWO questions:

**Question 1: "What Google services do you need? Just email, or also Calendar/Drive/Sheets/Docs?"**

- **Email only** → They don't need this skill at all. Use the `himalaya` skill instead — it works with a Gmail App Password (Settings → Security → App Passwords) and takes 2 minutes to set up. No Google Cloud project needed. Load the himalaya skill and follow its setup instructions.
- **Email + Calendar** → Continue with this skill, but use `--services email,calendar` during auth so the consent screen only asks for the scopes they actually need.
- **Calendar/Drive/Sheets/Docs only** → Continue with this skill and use a narrower `--services` set like `calendar,drive,sheets,docs`.
- **Full Workspace access** → Continue with this skill and use the default `all` service set.

**Question 2: "Does your Google account use Advanced Protection (hardware security keys required to sign in)? If you're not sure, you probably don't — it's something you would have explicitly enrolled in."**

- **No / Not sure** → Normal setup. Continue below.
- **Yes** → Their Workspace admin must add the OAuth client ID to the org's allowed apps list before Step 4 will work. Let them know upfront.

#### Step 2: Create OAuth credentials (one-time, ~5 minutes)

Tell the user:

> You need a Google Cloud OAuth client. This is a one-time setup:
>
> 1. Create or select a project:
>    https://console.cloud.google.com/projectselector2/home/dashboard
> 2. Enable the required APIs from the API Library:
>    https://console.cloud.google.com/apis/library
>    Enable: Gmail API, Google Calendar API, Google Drive API,
>    Google Sheets API, Google Docs API, People API
> 3. Create the OAuth client here:
>    https://console.cloud.google.com/apis/credentials
>    Credentials → Create Credentials → OAuth 2.0 Client ID
> 4. Application type: "Desktop app" → Create
> 5. If the app is still in Testing, add the user's Google account as a test user here:
>    https://console.cloud.google.com/auth/audience
>    Audience → Test users → Add users
> 6. Download the JSON file and tell me the file path
>
> Important Hermes CLI note: if the file path starts with `/`, do NOT send only the bare path as its own message in the CLI, because it can be mistaken for a slash command. Send it in a sentence instead, like:
> `The JSON file path is: /home/user/Downloads/client_secret_....json`

Once they provide the path:

```bash
$GSETUP --client-secret /path/to/client_secret.json
```

If they paste the raw client ID / client secret values instead of a file path, write a valid Desktop OAuth JSON file for them yourself, save it somewhere explicit (for example `~/Downloads/hermes-google-client-secret.json`), then run `--client-secret` against that file.

#### Step 3: Get authorization URL

Use the service set chosen in Step 1. Examples:

```bash
$GSETUP --auth-url --services email,calendar --format json
$GSETUP --auth-url --services calendar,drive,sheets,docs --format json
$GSETUP --auth-url --services all --format json
```

This returns JSON with an `auth_url` field and also saves the exact URL to `~/.hermes/google_oauth_last_url.txt`.

Agent rules for this step:
- Extract the `auth_url` field and send that exact URL to the user as a single line.
- Tell the user that the browser will likely fail on `http://localhost:1` after approval, and that this is expected.
- Tell them to copy the ENTIRE redirected URL from the browser address bar.
- If the user gets `Error 403: access_denied`, send them directly to `https://console.cloud.google.com/auth/audience` to add themselves as a test user.

#### Step 4: Exchange the code

The user will paste back either a URL like `http://localhost:1/?code=4/0A...&scope=...` or just the code string. Either works. The `--auth-url` step stores a temporary pending OAuth session locally so `--auth-code` can complete the PKCE exchange later, even on headless systems:

```bash
$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json
```

If `--auth-code` fails because the code expired, was already used, or came from an older browser tab, it now returns a fresh `fresh_auth_url`. In that case, immediately send the new URL to the user and have them retry with the newest browser redirect only.

#### Step 5: Verify

```bash
$GSETUP --check
```

Should print `AUTHENTICATED`. Setup is complete — token refreshes automatically from now on.

### Usage

All commands go through the API script. Set `GAPI` as a shorthand:

```bash
GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"
```

#### Gmail

```bash
# Search (returns JSON array with id, from, subject, date, snippet)
$GAPI gmail search "is:unread" --max 10
$GAPI gmail search "from:boss@company.com newer_than:1d"
$GAPI gmail search "has:attachment filename:pdf newer_than:7d"

# Read full message (returns JSON with body text)
$GAPI gmail get MESSAGE_ID

# Send
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1><p>Details...</p>" --html
$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" <user@example.com>' --body "Message text"

# Reply (automatically threads and sets In-Reply-To)
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
$GAPI gmail reply MESSAGE_ID --from '"Support Bot" <user@example.com>' --body "Thanks"

# Labels
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
```

#### Calendar

```bash
# List events (defaults to next 7 days)
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z

# Create event (ISO 8601 with timezone required)
$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
$GAPI calendar create --summary "Lunch" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Cafe"
$GAPI calendar create --summary "Review" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"

# Delete event
$GAPI calendar delete EVENT_ID
```

#### Drive

```bash
# Search existing files
$GAPI drive search "quarterly report" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5

# Get metadata for a single file
$GAPI drive get FILE_ID

# Upload a local file (auto-detects MIME type)
$GAPI drive upload /path/to/report.pdf
$GAPI drive upload /path/to/image.png --name "Logo.png" --parent FOLDER_ID

# Download (binary files download as-is; Google-native files export to a
# sensible default — Docs→pdf, Sheets→csv, Slides→pdf, Drawings→png)
$GAPI drive download FILE_ID
$GAPI drive download DOC_ID --output ~/doc.pdf
$GAPI drive download DOC_ID --export-mime text/plain --output ~/doc.txt

# Create a folder
$GAPI drive create-folder "Reports"
$GAPI drive create-folder "Q4" --parent FOLDER_ID

# Share
$GAPI drive share FILE_ID --email alice@example.com --role reader
$GAPI drive share FILE_ID --email alice@example.com --role writer --notify
$GAPI drive share FILE_ID --type anyone --role reader        # anyone with link
$GAPI drive share FILE_ID --type domain --domain example.com --role reader

# Delete — defaults to trash (reversible). Use --permanent to skip the trash.
$GAPI drive delete FILE_ID
$GAPI drive delete FILE_ID --permanent
```

#### Contacts

```bash
$GAPI contacts list --max 20
```

#### Sheets

```bash
# Create a new spreadsheet
$GAPI sheets create --title "Q4 Budget"
$GAPI sheets create --title "Inventory" --sheet-name "Stock"

# Read
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"

# Write
$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'

# Append rows
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
```

#### Docs

```bash
# Read
$GAPI docs get DOC_ID

# Create a new Doc (optionally seeded with body text)
$GAPI docs create --title "Meeting Notes"
$GAPI docs create --title "Draft" --body "First paragraph..."

# Append text to the end of an existing Doc
$GAPI docs append DOC_ID --text "Additional content to append"
```

### Output Format

All commands return JSON. Parse with `jq` or read directly. Key fields:

- **Gmail search**: `[{id, threadId, from, to, subject, date, snippet, labels}]`
- **Gmail get**: `{id, threadId, from, to, subject, date, labels, body}`
- **Gmail send/reply**: `{status: "sent", id, threadId}`
- **Calendar list**: `[{id, summary, start, end, location, description, htmlLink}]`
- **Calendar create**: `{status: "created", id, summary, htmlLink}`
- **Drive search**: `[{id, name, mimeType, modifiedTime, webViewLink}]`
- **Drive get**: `{id, name, mimeType, modifiedTime, size, webViewLink, parents, owners}`
- **Drive upload**: `{status: "uploaded", id, name, mimeType, webViewLink}`
- **Drive download**: `{status: "downloaded", id, name, path, mimeType}`
- **Drive create-folder**: `{status: "created", id, name, webViewLink}`
- **Drive share**: `{status: "shared", permissionId, fileId, role, type}`
- **Drive delete**: `{status: "trashed" | "deleted", fileId, permanent}`
- **Contacts list**: `[{name, emails: [...], phones: [...]}]`
- **Sheets get**: `[[cell, cell, ...], ...]`
- **Sheets create**: `{status: "created", spreadsheetId, title, spreadsheetUrl}`
- **Docs create**: `{status: "created", documentId, title, url}`
- **Docs append**: `{status: "appended", documentId, inserted_at, characters}`

### Hard Rules

1. **Never send email, create/delete calendar events, delete Drive files, share files, or modify Docs/Sheets without confirming with the user first.** Show what will be done (recipients, file IDs, content, share role) and ask for approval. For `drive delete`, prefer the default trash (reversible) over `--permanent`.
2. **Check auth before first use** — run `setup.py --check`. If it fails, guide the user through setup.
3. **Use the Gmail search syntax reference** for complex queries — load it with `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")`.
4. **Calendar times must include timezone** — always use ISO 8601 with offset (e.g., `2026-03-01T10:00:00-06:00`) or UTC (`Z`).
5. **Respect rate limits** — avoid rapid-fire sequential API calls. Batch reads when possible.

### Revoking Access

```bash
$GSETUP --revoke
```

## Pitfalls

| Problem | Fix |
|---------|-----|
| `NOT_AUTHENTICATED` | Run setup Steps 2–5 above |
| `REFRESH_FAILED` | Token revoked or expired — redo Steps 3–5 |
| `HttpError 403: Insufficient Permission` | Missing API scope — `$GSETUP --revoke` then redo Steps 3–5 |
| `AUTHENTICATED (partial)` or "Token missing scopes" | New write capabilities (Drive write/delete, Docs create/edit) require re-authorization. `$GSETUP --revoke` then redo Steps 3–5 to grant the upgraded scopes. |
| `HttpError 403: Access Not Configured` | API not enabled — user needs to enable it in Google Cloud Console |
| `ModuleNotFoundError` | Run `$GSETUP --install-deps` |
| Advanced Protection blocks auth | Workspace admin must allowlist the OAuth client ID |
| OAuth code expired / already used | `--auth-code` returns a `fresh_auth_url`; send the new URL to the user and retry with the newest browser redirect only |
| `Error 403: access_denied` during consent | User is not a test user — send them to `https://console.cloud.google.com/auth/audience` to add themselves |
| Bare `/path` mistaken for slash command in CLI | Always send file paths inside a sentence, e.g. `The JSON file path is: /home/user/Downloads/client_secret_....json` |
| Token stored at `~/.hermes/google_token.json` | Auto-refreshes; if `gws` is installed it shares the same token file — no separate `gws auth login` needed |
| Pending OAuth state at `~/.hermes/google_oauth_pending.json` | Temporary; cleared after exchange completes |

## Verification

1. **Auth check** — run after setup or before first use:
   ```bash
   $GSETUP --check
   ```
   Expected output: `AUTHENTICATED`

2. **Gmail read** — verify email access:
   ```bash
   $GAPI gmail search "is:unread" --max 1
   ```
   Expected: JSON array (possibly empty `[]` if no unread mail).

3. **Calendar read** — verify calendar access:
   ```bash
   $GAPI calendar list
   ```
   Expected: JSON array of upcoming events.

4. **Drive read** — verify Drive access:
   ```bash
   $GAPI drive search "" --max 1
   ```
   Expected: JSON array of file objects.

5. **Dependencies** — if any command raises `ModuleNotFoundError`:
   ```bash
   $GSETUP --install-deps
   ```
   Then re-run the failing command.

## Related Skills

- **himalaya** — Lightweight IMAP/SMTP email client. Prefer for email-only use cases to avoid the Google Cloud OAuth setup overhead. Works with a Gmail App Password.