// Set up and authenticate the gws CLI (@googleworkspace/cli) for Google Workspace access. Use when setting up OAuth, authenticating on headless/remote machines, configuring agent account access, or troubleshooting gws auth issues. For daily Gmail/Calendar/Drive usage, defer to the official gws skills shipped with the CLI.
Multi-phase writing workflow with voice analysis, parallel critique, and compounding learnings. Auto-triggers on writing tasks, content generation, drafting, editing, or style questions. Use /write for the full loop, /write:critique for standalone review, /write:polish for refinement. Triggers on: write, draft, substack, linkedin, email, newsletter, social post, voice, style, anti-slop, de-slop, content creation, blog post, article, chapter.
Design skills, CLIs, docs, and onboarding flows for AI coding agents. Use when writing agent skills, authoring SKILL.md files, designing CLI tools agents will use, creating onboarding READMEs, or reviewing any artifact where the primary consumer is a coding agent. Do NOT use for general technical writing or user-facing documentation.
Programmatic canvas toolkit for creating, editing, and refining Excalidraw diagrams via MCP tools with real-time canvas sync. Use when an agent needs to (1) draw or lay out diagrams on a live canvas, (2) iteratively refine diagrams using describe_scene and get_canvas_screenshot to see its own work, (3) export/import .excalidraw files or PNG/SVG images, (4) save/restore canvas snapshots, (5) convert Mermaid to Excalidraw, or (6) perform element-level CRUD, alignment, distribution, grouping, duplication, and locking. Requires a running canvas server (EXPRESS_SERVER_URL, default http://localhost:3000).
| name | google-workspace |
| description | Set up and authenticate the gws CLI (@googleworkspace/cli) for Google Workspace access. Use when setting up OAuth, authenticating on headless/remote machines, configuring agent account access, or troubleshooting gws auth issues. For daily Gmail/Calendar/Drive usage, defer to the official gws skills shipped with the CLI. |
Setup and auth for the gws CLI. For daily usage, generate the official per-service skills:
gws generate-skills # Creates gws-gmail, gws-calendar, gws-drive, etc.
See the full skills index.
npm install -g @googleworkspace/cli
gws auth setup # Creates GCP project, enables APIs, creates OAuth client (needs gcloud)
gws auth login # Opens browser for OAuth consent
When gws auth setup fails or you want control:
client_secret.json to ~/Library/Application Support/gws/ (macOS) or ~/.config/gws/ (Linux)gws auth login # All default scopes
gws auth login --readonly # Read-only scopes
gws auth login --scopes gmail.readonly,calendar,drive,tasks # Custom
gws auth login needs a browser. On headless machines:
With agent browser (OpenClaw): Run gws auth login in the background, open the printed OAuth URL via the browser tool (profile="user"), click through consent. Localhost redirect completes automatically since browser and CLI share the same host.
Without browser: Run gws auth login, open the URL on any machine, approve consent, copy the full redirect URL from the browser bar, extract the code param, and exchange it manually with curl or Python against https://oauth2.googleapis.com/token. Save the resulting refresh token as credentials.json.
Credentials are encrypted by default (AES-256-GCM). The CLI handles decryption and token refresh.
gws auth status # Shows account, scopes, credential location
gws auth export # Prints decrypted credentials (debugging only)
Recommended for AI assistants: authenticate as a dedicated agent account (e.g., agent@gmail.com). The user shares access to their data. User credentials never touch the agent machine.
Start with minimal scopes: gmail.readonly, drive, calendar, tasks
Gives the agent full read access to the user's entire inbox, sent mail, and thread history.
gws gmail +triage with userId: "user@gmail.com"gws gmail users messages list --params '{"userId": "user@gmail.com", "maxResults": 10}'
Security: Delegation technically grants send, but gmail.readonly scope rejects any write attempt at the API level. Two layers of protection.
Why not forwarding? Forwarding only gets new mail. Delegation reads the full inbox and thread history, which is critical for triage.
gws calendar events list --params '{"calendarId": "user@gmail.com", "singleEvents": true, "orderBy": "startTime", "timeMin": "..."}'
gws drive files list --params '{"q": "'\''user@gmail.com'\'' in owners"}'
With readonly scopes, write drafts as local markdown files for the user to review and send:
---
to: recipient@example.com
subject: Re: Original Subject
---
Draft body here...
| Scope | Access |
|---|---|
gmail.readonly | Read email only |
gmail.modify | Read + send + delete + labels |
calendar / calendar.readonly | Full / read-only calendar |
drive / drive.readonly | Full / read-only drive |
tasks / tasks.readonly | Full / read-only tasks |
Start with --readonly and expand only as needed.
| Problem | Fix |
|---|---|
| "Access blocked: app not verified" | Add account as test user in GCP > Auth Platform > Audience |
| "Google hasn't verified this app" | Expected for personal projects. Click Continue |
| 403 on API calls | Check API is enabled in GCP console |
| 403 "Delegation denied" | Takes up to 30 min to propagate after acceptance |
| Wrong account's data | gws auth status to check active credentials |
| Redirect fails during auth | Headless machine, use agent browser or manual exchange |