gws-setup

Name: gws-setup
Author: jezweb

937stars96forks

How to install gws-setup?

jezweb/claude-skills/gws-setup

$npx -y skills add jezweb/claude-skills --skill gws-setup

Installs into the current project.

Summary

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, instal

Files · 1

View on GitHub

SKILL.md

1	# Google Workspace CLI — First-Time Setup
2
3	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.
4
5	## Prerequisites
6
7	- Node.js 18+
8	- A Google account (personal or Workspace)
9	- Access to Google Cloud Console (console.cloud.google.com)
10
11	## Workflow
12
13	### Step 1: Pre-flight Checks
14
15	Check what's already done and skip completed steps:
16
17	```bash
18	# Check if gws is installed
19	which gws && gws --version
20
21	# Check if client_secret.json exists
22	ls ~/.config/gws/client_secret.json
23
24	# Check if already authenticated
25	gws auth status
26	```
27
28	If `gws auth status` shows `"status": "success"` with scopes, skip to Step 6 (Install Skills).
29
30	### Step 2: Install the CLI
31
32	```bash
33	npm install -g @googleworkspace/cli
34	gws --version
35	```
36
37	### Step 3: Create a GCP Project and OAuth Credentials
38
39	The user needs to create OAuth Desktop App credentials in Google Cloud Console. Walk them through each step.
40
41	3a. Create or select a GCP project:
42
43	Direct the user to: `https://console.cloud.google.com/projectcreate`
44
45	Or use an existing project. Ask the user which they prefer.
46
47	3b. Enable Google Workspace APIs:
48
49	Direct the user to the API Library for their project: `https://console.cloud.google.com/apis/library?project=PROJECT_ID`
50
51	Enable these APIs (search for each):
52	- Gmail API
53	- Google Drive API
54	- Google Calendar API
55	- Google Sheets API
56	- Google Docs API
57	- Google Chat API (requires extra Chat App config — see below)
58	- Tasks API
59	- People API
60	- Google Slides API
61	- Google Forms API
62	- Admin SDK API (optional — for Workspace admin features)
63
64	3c. Configure Google Chat App (required for Chat API):
65
66	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.
67
68	Direct the user to: `https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID`
69
70	1. Click the Configuration tab
71	2. Fill in app details (name, avatar, description — values don't matter for CLI use)
72	3. Under "Functionality", check Spaces and group conversations
73	4. Under "Connection settings", select Apps Script or HTTP endpoint (pick any — we just need the config to exist)
74	5. Save
75
76	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.
77
78	3e. Configure OAuth consent screen:
79
80	Direct the user to: `https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID`
81
82	Settings:
83	- User Type: External (works for any Google account)
84	- App name: `gws CLI` (or any name)
85	- User support email: their email
86	- Developer contact: their email
87	- Leave scopes blank (gws requests scopes at login time)
88	- Add their Google account as a test user (required while app is in "Testing" status)
89	- Save and continue through all screens
90
91	3f. Create OAuth client ID:
92
93	Direct the user to: `https://console.cloud.google.com/apis/credentials?project=PROJECT_ID`
94
95	1. Click Create Credentials → OAuth client ID
96	2. Application type: Desktop app
97	3. Name: `gws CLI`
98	4. Click Create
99	5. Copy the JSON or download the `client_secret_*.json` file
100
101	3g. Save the credentials:
102
103	Ask the user to provide the client_secret.json content (paste the JSON or provide the downloaded file path).
104
105	```bash
106	mkdir -p ~/.config/gws
107	```
108
109	Write the JSON to `~/.config/gws/client_secret.json`. The expected format:
110
111	```json
112	{
113	"installed": {
114	"client_id": "...",
115	"project_id": "...",
116	"auth_uri": "https://accounts.google.com/o/oauth2/auth",
117	"token_uri": "https://oauth2.googleapis.com/token",
118	"client_secret": "...",
119	"redirect_uris": ["http://localhost"]
120	}
121	}
122	```
123
124	### Step 4: Choose Scopes
125
126	Ask the user what level of access they want:
127
128	\| Option \| Command \| What it grants \|
129	\|--------\|---------\|----------------\|
130	\| Full access (recommended) \| `gws auth login --full` \| All Workspace scopes including admin, pubsub, cloud-platform \|
131	\| Core services \| `gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks` \| Most-used services only \|
132	\| Minimal \| `gws auth login -s gmail,calendar` \| Just email and calendar \|
133
134	Recommend full access for power users. The OAuth consent screen shows all requested scopes so the user can review before granting.
135
136	> Note: If the GCP app is in "Testing" status, scope selection is limited to ~25 scopes. Use `-s service1,service2` to

People who liked this also viewed

6 picks

Type

gws-setup

937stars96forks

View on GitHub

How to install gws-setup?

jezweb/claude-skills/gws-setup

$npx -y skills add jezweb/claude-skills --skill gws-setup

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Google Workspace CLI — First-Time Setup
2
3	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.
4
5	## Prerequisites
6
7	- Node.js 18+
8	- A Google account (personal or Workspace)
9	- Access to Google Cloud Console (console.cloud.google.com)
10
11	## Workflow
12
13	### Step 1: Pre-flight Checks
14
15	Check what's already done and skip completed steps:
16
17	```bash
18	# Check if gws is installed
19	which gws && gws --version
20
21	# Check if client_secret.json exists
22	ls ~/.config/gws/client_secret.json
23
24	# Check if already authenticated
25	gws auth status
26	```
27
28	If `gws auth status` shows `"status": "success"` with scopes, skip to Step 6 (Install Skills).
29
30	### Step 2: Install the CLI
31
32	```bash
33	npm install -g @googleworkspace/cli
34	gws --version
35	```
36
37	### Step 3: Create a GCP Project and OAuth Credentials
38
39	The user needs to create OAuth Desktop App credentials in Google Cloud Console. Walk them through each step.
40
41	3a. Create or select a GCP project:
42
43	Direct the user to: `https://console.cloud.google.com/projectcreate`
44
45	Or use an existing project. Ask the user which they prefer.
46
47	3b. Enable Google Workspace APIs:
48
49	Direct the user to the API Library for their project: `https://console.cloud.google.com/apis/library?project=PROJECT_ID`
50
51	Enable these APIs (search for each):
52	- Gmail API
53	- Google Drive API
54	- Google Calendar API
55	- Google Sheets API
56	- Google Docs API
57	- Google Chat API (requires extra Chat App config — see below)
58	- Tasks API
59	- People API
60	- Google Slides API
61	- Google Forms API
62	- Admin SDK API (optional — for Workspace admin features)
63
64	3c. Configure Google Chat App (required for Chat API):
65
66	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.
67
68	Direct the user to: `https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID`
69
70	1. Click the Configuration tab
71	2. Fill in app details (name, avatar, description — values don't matter for CLI use)
72	3. Under "Functionality", check Spaces and group conversations
73	4. Under "Connection settings", select Apps Script or HTTP endpoint (pick any — we just need the config to exist)
74	5. Save
75
76	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.
77
78	3e. Configure OAuth consent screen:
79
80	Direct the user to: `https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID`
81
82	Settings:
83	- User Type: External (works for any Google account)
84	- App name: `gws CLI` (or any name)
85	- User support email: their email
86	- Developer contact: their email
87	- Leave scopes blank (gws requests scopes at login time)
88	- Add their Google account as a test user (required while app is in "Testing" status)
89	- Save and continue through all screens
90
91	3f. Create OAuth client ID:
92
93	Direct the user to: `https://console.cloud.google.com/apis/credentials?project=PROJECT_ID`
94
95	1. Click Create Credentials → OAuth client ID
96	2. Application type: Desktop app
97	3. Name: `gws CLI`
98	4. Click Create
99	5. Copy the JSON or download the `client_secret_*.json` file
100
101	3g. Save the credentials:
102
103	Ask the user to provide the client_secret.json content (paste the JSON or provide the downloaded file path).
104
105	```bash
106	mkdir -p ~/.config/gws
107	```
108
109	Write the JSON to `~/.config/gws/client_secret.json`. The expected format:
110
111	```json
112	{
113	"installed": {
114	"client_id": "...",
115	"project_id": "...",
116	"auth_uri": "https://accounts.google.com/o/oauth2/auth",
117	"token_uri": "https://oauth2.googleapis.com/token",
118	"client_secret": "...",
119	"redirect_uris": ["http://localhost"]
120	}
121	}
122	```
123
124	### Step 4: Choose Scopes
125
126	Ask the user what level of access they want:
127
128	\| Option \| Command \| What it grants \|
129	\|--------\|---------\|----------------\|
130	\| Full access (recommended) \| `gws auth login --full` \| All Workspace scopes including admin, pubsub, cloud-platform \|
131	\| Core services \| `gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks` \| Most-used services only \|
132	\| Minimal \| `gws auth login -s gmail,calendar` \| Just email and calendar \|
133
134	Recommend full access for power users. The OAuth consent screen shows all requested scopes so the user can review before granting.
135
136	> Note: If the GCP app is in "Testing" status, scope selection is limited to ~25 scopes. Use `-s service1,service2` to

People who liked this also viewed

6 picks

Type