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.