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

gws auth status

shows

"status": "success"

with scopes, skip to Step 6 (Install Skills).

Step 2: Install the CLI

bash

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
Tasks API
People API
Google Slides API
Google Forms API
Admin SDK API (optional — for Workspace admin features)

3c. 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

3d. 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_*.json
```
file

3e. Save the credentials:

Ask the user to provide the client_secret.json content (paste the JSON or provide the downloaded file path).

bash

mkdir -p ~/.config/gws

Write the JSON to

~/.config/gws/client_secret.json

. The expected format:

json

{
  "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,service2
to request targeted scopes, or publish the app (Publish → In Production) for broader scope access.

Step 5: Authenticate

Run the login command. This opens a browser — the user signs in with their chosen Google account and approves the scopes.

bash

gws auth login --full
# Or with specific services:
gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks

After browser approval, gws stores encrypted credentials at

~/.config/gws/credentials.enc

Verify:

bash

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:

bash

npx skills add googleworkspace/cli -g --agent claude-code --all

Verify skills are installed:

bash

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:

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

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:

bash

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

gws-setup

NPX Install

Tags

SKILL.md Content

Google Workspace CLI — First-Time Setup

Prerequisites

Workflow

Step 1: Pre-flight Checks

Step 2: Install the CLI

Step 3: Create a GCP Project and OAuth Credentials

Step 4: Choose Scopes

Step 5: Authenticate

Step 6: Install Agent Skills

Step 7: Save Credentials for Other Machines

Step 8: Verify Everything Works

Critical Patterns

Testing vs Production OAuth Apps

Scope Reference

Environment Variable Alternative

Config Directory

See Also