/google-workspace

name: google-workspace
description: "Access Google Workspace APIs (Drive, Docs, Calendar, Gmail, Sheets, Slides, Chat, People) via local helper scripts without MCP. Handles OAuth login and direct API calls."

Google Workspace

Use this skill for Google Workspace tasks (Gmail, Drive, Calendar, Docs, Sheets, etc.).

Files

• `scripts/auth.js` — OAuth login/status/clear + account enumeration
• `scripts/workspace.js` — JavaScript execution based API runner

Account model (multi-account)

This skill is **profile-based by email address**.

• There is **no default account**.
• Every API call must specify `--email <account@example.com>`.
• Tokens are stored per-email under `~/.pi/google-workspace/tokens/`.

Before running API calls, discover available signed-in accounts:

node scripts/auth.js accounts

Usage

Always use `exec` and always provide `--email`.

node scripts/workspace.js exec --email user@example.com <<'JS'
const me = await workspace.whoAmI();
const files = await workspace.call('drive', 'files.list', {
  pageSize: 5,
  fields: 'files(id,name,mimeType)',
});
return { me, files: files.files };
JS

Available inside exec scripts:

• `auth` (authorized OAuth client)
• `google` (`googleapis` root)
• `workspace.accountEmail` (selected profile email)
• `workspace.call(service, methodPath, params, {version})`
• `workspace.service(service, {version})`
• `workspace.whoAmI()`

Optional flags:

• `--timeout <ms>` (default 30000, max 300000)
• `--scopes s1,s2`
• `--script 'return 42'`

Agent guidance

1. Prefer one `exec` script per user request. 2. Keep payloads small (`fields`, `maxResults`, minimal props). 3. Use `Promise.all` for independent requests. 4. Never print token contents. 5. If the user did not specify an account, run `node scripts/auth.js accounts` and choose/confirm an explicit email. 6. If auth fails, first run `node scripts/auth.js accounts` to see known profiles. 7. If account mismatch is possible, run `workspace.whoAmI()` in the selected profile. 8. On 401/403/unauthorized errors, switch account (`--email ...`) or re-login that specific profile.

Unauthorized/account-switch playbook

If a request fails with unauthorized/forbidden/insufficient permissions:

1. Enumerate profiles:

node scripts/auth.js accounts

2. Retry with the intended account:

node scripts/workspace.js exec --email correct-user@example.com <<'JS'
return await workspace.whoAmI();
JS

3. If token is stale or missing scopes, re-login that account:

node scripts/auth.js login --email correct-user@example.com

4. Retry the original request with the same `--email`.

Short Gmail counting example

node scripts/workspace.js exec --email user@example.com <<'JS'
const gmail = google.gmail({ version: 'v1', auth });

let trash = 0;
let pageToken;
do {
  const res = await gmail.users.messages.list({
    userId: 'me',
    q: 'in:trash',
    maxResults: 500,
    pageToken,
    fields: 'messages/id,nextPageToken',
  });
  trash += (res.data.messages || []).length;
  pageToken = res.data.nextPageToken;
} while (pageToken);

return { currentlyInTrash: trash };
JS

Setup + auth

node scripts/auth.js login --email user@example.com

Notes:

• Dependencies auto-install on first run.
• Default auth mode is **cloud** (no local `credentials.json` needed).
• Optional local mode: `GOOGLE_WORKSPACE_AUTH_MODE=local` and credentials at `~/.pi/google-workspace/credentials.json`.
• Useful diagnostics:

node scripts/auth.js accounts
node scripts/auth.js status --email user@example.com
node scripts/auth.js clear --email user@example.com