Set up the Google Workspace CLI (gws) from scratch. Guides through GCP project creation, OAuth credentials, authentication, and installing 90+ agent skills for Claude Code. Use whenever the user wants to set up gws for the first time, configure Google Workspace API access,
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/gws-setup
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Set up the Google Workspace CLI (gws) from scratch. Guides through GCP project creation, OAuth credentials, authentication, and installing 90+ agent skills for Claude Code. Use whenever the user wants to set up gws for the first time, configure Google Workspace API access,
📊 Stats
Stars940
Forks96
LanguagePython
LicenseMIT
📦 Ships with jezweb-skills
</> SKILL.md
gws-setup.SKILL.md
---name: gws-setup
description: "Set up the Google Workspace CLI (gws) from scratch. Guides through GCP project creation, OAuth credentials, authentication, and installing 90+ agent skills for Claude Code. Use whenever the user wants to set up gws for the first time, configure Google Workspace API access, install the Google Workspace CLI, or troubleshoot gws auth issues."
compatibility: claude-code-only
---# Google Workspace CLI — First-Time Setup
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.
## Prerequisites
- Node.js 18+
- A Google account (personal or Workspace)
- Access to Google Cloud Console (console.cloud.google.com)
## Workflow
### Step 1: Pre-flight Checks
Check what's already done and skip completed steps:
```bash
# 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).
### Step 3: Create a GCP Project and OAuth Credentials
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):
- Gmail API
- Google Drive API
- Google Calendar API
- Google Sheets API
- Google Docs API
- Google Chat API (requires extra Chat App config — see below)
- Tasks API
- People API
- Google Slides API
- Google Forms API
- Admin SDK API (optional — for Workspace admin features)
**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`
1. Click the **Configuration** tab
2. Fill in app details (name, avatar, description — values don't matter for CLI use)
3. Under "Functionality", check **Spaces and group conversations**
4. Under "Connection settings", select **Apps Script** or **HTTP endpoint** (pick any — we just need the config to exist)
5. Save
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:
- User Type: **External** (works for any Google account)
- App name: `gws CLI` (or any name)
- User support email: their email
- Developer contact: their email
- Leave scopes blank (gws requests scopes at login time)
- Add their Google account as a test user (required while app is in "Testing" status)
- Save and continue through all screens
**3f. Create OAuth client ID:**
Direct the user to: `https://console.cloud.google.com/apis/credentials?project=PROJECT_ID`
| **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,service2` to request targeted scopes, or publish the app (Publish → In Production) for broader scope access.
### Step 5: Authenticate
**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.
1. Run the login command and capture the output:
```bash
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.
2. Extract and open the URL (run separately after output appears):
If the user has other machines to set up, suggest exporting the client credentials:
```bash
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.
### Step 8: Verify Everything Works
Run a few commands to confirm:
```bash
# 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.
---
## Critical Patterns
### Testing vs Production OAuth Apps
GCP OAuth apps start in "Testing" status with a 7-day token expiry and ~25 scope limit. For long-term use:
- Push the app to **Production** in the OAuth consent screen settings
- Production apps have no token expiry limit
- For personal/internal use, Google does not require verification
