Google Workspace

---
name: google-workspace
description: >
  Google Workspace CLI — routes to service-specific skills for Gmail, Sheets, Calendar, Tasks,
  Docs, Forms, Drive, Analytics and Search Console.
  TRIGGERS: "gmail", "email", "send email", "inbox", "calendar", "meeting", "sheets",
  "spreadsheet", "tasks", "google docs", "gdoc", "outreach", "google form", "form responses",
  "create google form", "feedback form", "survey form", "google analytics", "GA4", "traffic",
  "sessions", "visitors", "search console", "GSC", "what are we ranking for", "search queries",
  "impressions", "clicks", "SEO"
---

# Google Workspace CLI

Routes to service-specific skills. Use the right skill for your task:

| Need | Skill |
|------|-------|
| Send, draft, reply, reply-all, manage email (with attachments) | **gw-gmail** |
| Quick inbox check | **gw-inbox** |
| Read/write spreadsheets | **gw-sheets** |
| Schedule meetings | **gw-calendar** |
| Manage to-dos | **gw-tasks** |
| Read/create/edit documents | **gw-docs** |
| Create / edit Google Forms, read metadata and responses | **gw-forms** |
| List, upload, download, share, organize Drive files & folders | **gw-drive** |
| Read GA4 traffic, acquisition, pages, conversions, realtime | **gw-analytics** |
| Read Search Console queries, pages, CTR, position, indexing, sitemaps | **gw-searchconsole** |
| Call ANY Google API method (Discovery), inspect schemas | **gw-api** |

**Attachments are supported** on every sending verb: `send`, `draft`, `draft-reply`, `draft-reply-all`, `reply`, `reply-all`, `update-draft`, and `attach-to-draft`. Use `--attach /path/to/file` and repeat for multiple files. See **gw-gmail** skill for examples.

**Signature is appended by default** on every sending verb (the account's Gmail send-as signature). Pass `--no-signature` to omit it, or `--plain` on `send`, `draft` and the reply verbs to send plain text only (no HTML, signature or styling), or `--html-body HTML` on the same verbs to send your own HTML part verbatim (no signature). See **gw-gmail**.

**Draft modification is supported.** Full lifecycle: `list-drafts` → `get-draft` → `update-draft` / `attach-to-draft` → `send-draft` or `delete-draft`. See **gw-gmail**.

**Reply auto-preserves original Cc** on `reply` and `draft-reply`. Reply-all expands Cc to include original To recipients. See **gw-gmail** for the `--cc` / `--no-cc` override semantics.

## Opt-in scopes

`gw-analytics` and `gw-searchconsole` need scopes a default login does **not** grant. Add them
without losing the rest of the token:

```bash
$CLI auth login --add-scopes analytics,searchconsole
```

Use `--add-scopes`, never `--scopes`: a login **replaces** the token, so `--scopes analytics`
would drop Gmail, Calendar, Drive, Sheets, Docs, Tasks and Forms. Both scopes are read-only.

`postmaster` (`postmaster.traffic.readonly`, read-only) reaches Gmail Postmaster Tools v2 through
`gw-api`: `$CLI auth login --add-scopes postmaster`, then
`$CLI api call gmailpostmastertools:v2 domains.getComplianceStatus --params '{"name":"domains/example.com/complianceStatus"}'`.

## UI Verification

All write operations (calendar create/update, docs create/append/replace, forms create/add-items, sheets write/append, gmail draft) should be verified visually using Chrome DevTools MCP (`mcp__chrome-devtools__navigate_page` + `mcp__chrome-devtools__take_screenshot`). Each service skill has specific verification steps — follow them before reporting done.

## CLI

```bash
CLI="python3 ${CLAUDE_PLUGIN_ROOT}/cli/gw.py"
```

## Auth Troubleshooting

Auth tokens live under `~/.config/gw/`, with a legacy fallback to `.google-token*.json` files at the **repo root**. The CLI finds them automatically — it is **CWD-independent**. If auth seems broken:

1. Check auth state: `gw auth status`
2. Read `${CLAUDE_PLUGIN_ROOT}/lib/auth.py` to understand resolution — do NOT guess paths
3. **Never** point to plugin cache paths (`~/.claude/plugins/cache/...`) — that's not where auth lives
4. Re-auth only if the token is genuinely missing: `gw auth login --account <name>`

## Account Routing

Accounts are user-defined in `accounts.json` (see `gw auth list` / `gw auth login --account <name>`); the names and emails below are only examples.

| Account | Example email | Typical use |
|---|---|---|
| `--account main` | `you@example.com` | Primary (default) |
| `--account work` | `work@example.com` | Work / outreach |
| `--account personal` | `personal@example.com` | Personal |

Use a dedicated outreach account (e.g. `--account work`) for outreach rather than your primary. Never default to `personal` — it must be passed explicitly. All commands output JSON; add `--compact` to save tokens.

The `cold-outreach` agent was retired with the sender in 1.3.2. Draft outreach with `/draft-email`.