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