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

**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,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.

- 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