gws-setup
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.
- Installs
- 1.1K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/jezweb/claude-skills --skill gws-setup- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads gws-setup automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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:
# 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 2: Install the CLI
npm install -g @googleworkspace/cli
gws --version
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
- Click the Configuration tab
- Fill in app details (name, avatar, description — values don't matter for CLI use)
- Under "Functionality", check Spaces and group conversations
- Under "Connection settings", select Apps Script or HTTP endpoint (pick any — we just need the config to exist)
- 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
- Click Create Credentials → OAuth client ID
- Application type: Desktop app
- Name:
gws CLI - Click Create
- Copy the JSON or download the
client_secret_*.jsonfile
3g. 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"]
}
}
Step 4: Choose Scopes
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.
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.
- Run the login command and capture the output:
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.
- Extract and open the URL (run separately after output appears):
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."
- Wait for the user to approve in their browser.
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.
Step 6: Install Agent Skills
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.
Step 7: Save Credentials for Other Machines
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.
Step 8: Verify Everything Works
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.
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
Scope Reference
| 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) |
Environment Variable Alternative
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
Config Directory
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 |
See Also
- gws-install — Quick setup on additional machines with existing credentials
- gws-shared — Auth patterns and global flags for gws commands
FAQ
What does the gws-setup skill do?
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.
How do I install gws-setup?
Run npx skills add https://github.com/jezweb/claude-skills --skill gws-setup in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/gws-setup/ (personal) or .claude/skills/gws-setup/ (project).
Which AI agents can use gws-setup?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is gws-setup safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains gws-setup?
It is published by jezweb in jezweb/claude-skills. It has 1,109 recorded installs.
More from jezweb/claude-skills
shadcn-ui
jezweb/claude-skills
Install and configure shadcn/ui components for React projects. Guides component selection, installation order, dependency management, customisation with semantic tokens, and common UI recipes (forms, data tables, navigation, modals). Use after tailwind-theme-builder has set up the theme infrastructure, when adding components, building forms, creating data tables, or setting up navigation.
color-palette
jezweb/claude-skills
Generate complete, accessible colour palettes from a single brand hex. Produces 11-shade scale (50-950), semantic tokens, dark mode variants, Tailwind v4 CSS output, WCAG contrast checks. Use whenever the user supplies a brand hex and asks for a palette, mentions setting up a design system, wants Tailwind theme colours from a brand colour, or asks to check colour accessibility / contrast.
tailwind-theme-builder
jezweb/claude-skills
Set up Tailwind v4 + shadcn/ui themed UI with dark mode. Install deps, configure CSS variables via @theme inline, wire dark mode toggle, verify. Use whenever the user mentions Tailwind v4, setting up Tailwind theming, shadcn/ui colours, dark mode, or troubleshooting colours not working, tw-animate-css errors, @theme inline conflicts, @apply breaking after upgrade, or v3 → v4 migration issues.
wordpress-elementor
jezweb/claude-skills
Edit Elementor pages and manage templates on WordPress sites via browser automation (for visual / structural changes) or WP-CLI (for safe text replacements). Use whenever the user wants to edit an Elementor page, update text in Elementor widgets, apply or manage Elementor templates, or make content changes to pages built with the Elementor page builder.
ux-audit
jezweb/claude-skills
Walk through a live web app AS a real user to find usability + behavioural bugs that static reviews miss. REQUIRES proof of interaction (typing, clicking, sending, observing) before any verdict — a sweep that didn't interact terminates with verdict 'Incomplete'. Walks threads, exercises every element, runs the multi-pane stress matrix, visual polish sweep, component perfection checklist, automated a11y (axe-core), pragmatic performance budget (LCP/CLS/INP), scenario battery (11 scenarios), and stress recipes including the real-flavour data battery. Hard gates: console errors/warnings = 0, network 5xx = 0, layout collapse = 0, axe Critical/Serious = 0, perf budget green. Audit-the-audit meta-check rejects rushed reports. Each finding has reproduction steps, evidence path, and suspected code location. Trigger with 'ux audit', 'walkthrough', 'qa sweep', 'audit the app', 'dogfood this', 'check all pages', 'find what's broken', 'stress the UI'.
tailwind-v4-shadcn
jezweb/claude-skills
Set up Tailwind v4 with shadcn/ui using @theme inline pattern and CSS variable architecture. Four-step pattern: CSS variables, Tailwind mapping, base styles, automatic dark mode. Prevents 8 documented errors. Use when initializing React projects with Tailwind v4, or fixing colors not working, tw-animate-css errors, @theme inline dark mode conflicts, @apply breaking, v3 migration issues.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.