From integrations
Guides Google Workspace CLI (gws) setup: installs via npm, creates GCP project, configures OAuth and APIs (Gmail/Drive/etc.), authenticates, installs Claude Code skills. For first-time use or auth troubleshooting.
npx claudepluginhub jezweb/claude-skills --plugin integrationsThis skill uses the workspace's default tool permissions.
Set up the `gws` CLI (@googleworkspace/cli) with OAuth credentials and 90+ agent skills for Claude Code. Produces a fully authenticated CLI with skills for Gmail, Drive, Calendar, Sheets, Docs, Chat, Tasks, and more.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Set up the gws CLI (@googleworkspace/cli) with OAuth credentials and 90+ agent skills for Claude Code. Produces a fully authenticated CLI with skills for Gmail, Drive, Calendar, Sheets, Docs, Chat, Tasks, and more.
Check what's already done and skip completed steps:
# Check if gws is installed
which gws && gws --version
# Check if client_secret.json exists
ls ~/.config/gws/client_secret.json
# Check if already authenticated
gws auth status
If gws auth status shows "status": "success" with scopes, skip to Step 6 (Install Skills).
npm install -g @googleworkspace/cli
gws --version
The user needs to create OAuth Desktop App credentials in Google Cloud Console. Walk them through each step.
3a. Create or select a GCP project:
Direct the user to: https://console.cloud.google.com/projectcreate
Or use an existing project. Ask the user which they prefer.
3b. Enable Google Workspace APIs:
Direct the user to the API Library for their project: https://console.cloud.google.com/apis/library?project=PROJECT_ID
Enable these APIs (search for each):
3c. Configure Google Chat App (required for Chat API):
Enabling the Chat API alone isn't enough — Google requires a Chat App configuration even for user-context OAuth access. Without this, all Chat API calls return errors.
Direct the user to: https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID
This creates the app identity that the Chat API requires. Messages sent via gws still appear as coming from the authenticated user (OAuth user context), not from a bot.
3e. Configure OAuth consent screen:
Direct the user to: https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID
Settings:
gws CLI (or any name)3f. Create OAuth client ID:
Direct the user to: https://console.cloud.google.com/apis/credentials?project=PROJECT_ID
gws CLIclient_secret_*.json file3g. Save the credentials:
Ask the user to provide the client_secret.json content (paste the JSON or provide the downloaded file path).
mkdir -p ~/.config/gws
Write the JSON to ~/.config/gws/client_secret.json. The expected format:
{
"installed": {
"client_id": "...",
"project_id": "...",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"client_secret": "...",
"redirect_uris": ["http://localhost"]
}
}
Ask the user what level of access they want:
| Option | Command | What it grants |
|---|---|---|
| Full access (recommended) | gws auth login --full | All Workspace scopes including admin, pubsub, cloud-platform |
| Core services | gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks | Most-used services only |
| Minimal | gws auth login -s gmail,calendar | Just email and calendar |
Recommend full access for power users. The OAuth consent screen shows all requested scopes so the user can review before granting.
Note: If the GCP app is in "Testing" status, scope selection is limited to ~25 scopes. Use
-s service1,service2to request targeted scopes, or publish the app (Publish → In Production) for broader scope access.
IMPORTANT: This step prints a very long OAuth URL (30+ scopes) that the user must open in their browser. The URL is too long to copy from terminal output — it wraps across lines and breaks. Always extract it to a file and open it programmatically.
gws auth login --full 2>&1 | tee /tmp/gws-auth-output.txt
# Or with specific services:
# gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks 2>&1 | tee /tmp/gws-auth-output.txt
Running as a background task is fine — it will complete once the user approves in browser.
grep -o 'https://accounts.google.com[^ ]*' /tmp/gws-auth-output.txt > /tmp/gws-auth-url.txt
cat /tmp/gws-auth-url.txt | xargs open
If open doesn't work, tell the user: "The auth URL is saved at /tmp/gws-auth-url.txt — open that file and copy the URL."
After browser approval, gws stores encrypted credentials at ~/.config/gws/credentials.enc.
Verify:
gws auth status
Should show "status": "success" with the authenticated account and granted scopes.
Install the 90+ gws agent skills globally for Claude Code:
npx skills add googleworkspace/cli -g --agent claude-code --all
Verify skills are installed:
ls ~/.claude/skills/gws-* | wc -l
Should show 30+ gws skill directories.
If the user has other machines to set up, suggest exporting the client credentials:
gws auth export
This prints decrypted credentials (including refresh token) to stdout. The client_secret.json file is the portable part — the same OAuth client can be used on any machine, with gws auth login generating fresh user tokens per machine.
Tell the user to save the client_secret.json content somewhere secure (password manager, encrypted note) for use with the gws-install skill on other machines.
Run a few commands to confirm:
# Check auth
gws auth status
# Check calendar
gws calendar +agenda --today
# Check email
gws gmail +triage
If any command fails with auth errors, re-run gws auth login with the needed scopes.
GCP OAuth apps start in "Testing" status with a 7-day token expiry and ~25 scope limit. For long-term use:
| Service flag | What it enables |
|---|---|
gmail | Send, read, manage email, labels, filters |
drive | Files, folders, shared drives |
calendar | Events, calendars, free/busy |
sheets | Read and write spreadsheets |
docs | Read and write documents |
chat | Spaces, messages |
tasks | Task lists and tasks |
slides | Presentations |
forms | Forms and responses |
people | Contacts and profiles |
admin | Workspace admin (directory, devices, groups) |
Instead of client_secret.json, credentials can be provided via environment variables:
export GOOGLE_WORKSPACE_CLI_CLIENT_ID="your-client-id"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="your-client-secret"
gws auth login
All gws config lives in ~/.config/gws/:
| File | Purpose |
|---|---|
client_secret.json | OAuth client credentials (portable) |
credentials.enc | Encrypted user tokens (per-machine) |
token_cache.json | Token refresh cache |
cache/ | API discovery schema cache |