Gws Setup

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

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

1. Click Create Credentials → OAuth client ID
2. Application type: Desktop app
3. Name: gws CLI
4. Click Create
5. 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:

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.