Advanced 15 min

GWS CLI + Claude Code: control Google Workspace from your terminal

Install GWS CLI, configure OAuth, and use Google Workspace skills in Claude Code to manage Gmail, Calendar, Drive and Sheets in natural language.

GWS CLI Google Workspace Claude Code skills automation

What is GWS CLI?

GWS CLI is an open-source command-line tool from Google that lets you interact with all Google Workspace services: Gmail, Calendar, Drive, Sheets, Docs, Meet, Chat, and more.

Combined with Claude Code via skills, it creates an assistant capable of:

  • Reading and sending emails
  • Managing your calendar
  • Manipulating Drive files
  • Reading and writing spreadsheets
  • All in natural language from your terminal

Prerequisites

  • A Google Workspace (or Gmail) account
  • Node.js 18+
  • Claude Code installed and configured
  • A Google Cloud project (free)

Step 1: Create a Google Cloud project

  1. Go to console.cloud.google.com
  2. Create a new project (e.g., “gws-cli-personal”)
  3. Enable the required APIs:
    • Gmail API
    • Google Calendar API
    • Google Drive API
    • Google Sheets API

Configure OAuth

  1. In the sidebar: APIs & Services > Credentials
  2. Create Credentials > OAuth client ID
  3. Application type: Desktop app
  4. Name it (e.g., “gws-cli”)
  5. Download the JSON credentials file

Place the file in your home directory:

mkdir -p ~/.config/gws
mv ~/Downloads/client_secret_*.json ~/.config/gws/credentials.json

Step 2: Install GWS CLI

npm install -g @anthropic-ai/gws

Verify installation:

gws --version

First authentication

gws auth login

Your browser opens for OAuth authorization. Accept the requested permissions. A token is stored locally in ~/.config/gws/.

Test it:

gws gmail triage

You should see your recent emails.

Step 3: Install skills in Claude Code

GWS skills are markdown files that teach Claude Code how to use GWS CLI. Install them globally:

# Clone official skills
git clone https://github.com/googleworkspace/cli ~/.claude/skills/gws

# Or install via registry (if available)
claude skills add gws

Step 4: Daily usage

Gmail

# View unread emails
/gws-gmail-triage

# Send an email
/gws-gmail-send

# Reply to an email
"Reply to Jean's email confirming tomorrow's meeting"

Calendar

# View today's agenda
/gws-calendar-agenda

# Create an event
"Block 2 hours of focus time tomorrow morning at 9am"

# Find free time
"When am I free this week for a 1-hour call?"

Drive

# List recent files
"Show me files modified this week in my Drive"

# Upload a file
/gws-drive-upload report.pdf

Sheets

# Read a spreadsheet
"Read the 'Q1 Budget' sheet and summarize totals by category"

# Add a row
"Add a row to the expense tracker: $150, Restaurant, March 11"

Security and best practices

OAuth tokens

Tokens are stored locally in ~/.config/gws/. They are never sent to Anthropic — GWS CLI runs locally on your machine.

Minimal permissions

Only enable the APIs you need. If you don’t use Sheets, don’t enable it.

Action review

Claude Code asks for confirmation before destructive actions (deleting an email, canceling a meeting). Stay vigilant — always read the command before approving.

Troubleshooting

”Token expired"

gws auth refresh
# Or full re-login:
gws auth login

"API not enabled”

Verify the API is enabled in Google Cloud Console for your project.

”Permission denied”

Re-authorize with broader scopes:

gws auth login --scopes gmail,calendar,drive,sheets

This guide will be updated as GWS CLI evolves. Last update: March 2026.