---
title: "Google Workspace CLI Reference"
description: "Reference for gws, a unified CLI for Google Drive, Gmail, Calendar, and Sheets APIs. Covers authentication, command structure, common operations, Sheets range escaping, and key spreadsheet IDs."
type: reference
domain: productivity
tags: [gws, google-workspace, drive, gmail, calendar, sheets, oauth, cli]
---

# Google Workspace CLI (gws)

## Overview
`gws` is a unified CLI for all Google Workspace APIs — Drive, Gmail, Calendar, Sheets, and more. It reads Google's Discovery Service at runtime and builds its command surface dynamically. Installed for use by Claude via Bash for querying and managing Google Workspace resources.

- **Binary**: `/usr/local/bin/gws` | **Version**: 0.11.1
- **Repo**: https://github.com/googleworkspace/cli
- **Config dir**: `~/.config/gws/`
- **Not an officially supported Google product**

## Dependencies
- **gcloud SDK**: `/opt/google-cloud-sdk/` (added to fish PATH via `config.fish`)
- **Node.js 18+**: Required for npm install route

## Authentication
- OAuth scopes authenticated: `drive`, `gmail`, `calendar`, `sheets`
- Google Cloud project: "Claude Home"
- Credentials encrypted at rest (AES-256-GCM) via OS keyring
- Cal added as test user on OAuth consent screen (required for unverified/testing apps)
- Unverified apps limited to ~25 scopes — use `gws auth login -s service1,service2` to stay under limit

### Re-authenticating or Adding Scopes
```bash
gws auth login -s drive,gmail,calendar,sheets,docs
```

## Usage

### Command Structure
```
gws <service> <resource> [sub-resource] <method> [flags]
```

Subcommands are **space-separated** (not dot-notation):
```bash
gws sheets spreadsheets values get    # correct
gws sheets spreadsheets.values get    # WRONG
```

### Common Commands

#### Drive
```bash
# List files
gws drive files list --params '{"pageSize": 10}'

# Search files
gws drive files list --params '{"q": "name contains \"keyword\""}'

# Upload a file
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
```

#### Sheets
```bash
# Read cells — use \u0021 for ! in double-quoted JSON (bash history expansion)
gws sheets spreadsheets values get \
  --params "{\"spreadsheetId\": \"SHEET_ID\", \"range\": \"SheetName\u0021A1:Z50\"}"

# Or use single quotes (safe in fish, careful in bash)
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:C10"}'

# Append rows
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

# List all tabs in a spreadsheet
gws sheets spreadsheets get --params '{"spreadsheetId": "ID", "fields": "sheets.properties.title"}'
```

#### Gmail
```bash
# List unread messages
gws gmail users messages list --params '{"userId": "me", "q": "is:unread"}'

# Read a message
gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID"}'
```

#### Calendar
```bash
# List upcoming events
gws calendar events list --params '{"calendarId": "primary", "maxResults": 5}'
```

### Flags Reference
| Flag | Description | Default |
|------|-------------|---------|
| `--params <JSON>` | URL/Query parameters | — |
| `--json <JSON>` | Request body (POST/PATCH/PUT) | — |
| `--upload <PATH>` | File to upload (multipart) | — |
| `--output <PATH>` | Output file for binary responses | — |
| `--format <FMT>` | Output: json, table, yaml, csv | json |
| `--page-all` | Auto-paginate as NDJSON | off |
| `--page-limit <N>` | Max pages with --page-all | 10 |
| `--dry-run` | Preview request without executing | off |

### Introspecting APIs
```bash
# See full schema for any method
gws schema drive.files.list
gws schema sheets.spreadsheets.values.get
```

## Known Gotchas
- **Sheets `!` in ranges**: Bash history expansion mangles `!`. Use `\u0021` in double-quoted JSON, or single quotes
- **Scope limit**: Unverified OAuth apps cap at ~25 scopes. Specify only needed services with `-s`
- **No MCP server mode**: Use via Bash only — all output is structured JSON
- **First run may be slow**: Discovery service data is fetched and cached (24-hour cache)

## Key Spreadsheets
| ID | Description |
|----|-------------|
| `1ctsjx41Muy5QXvVGvpT_8ovBc5HP_YLSJSqNRUOYidM` | SBA scorecard s13w12g04 (DEN vs WV) |
| `1K7OBSrXY3NIXUaFLn4DZRI1_P7yv-5uaVSHLSEdx1VY` | Master Umpire Central |
| `1QU5hTrNp8GuKi4FJ6AigPT54J0JtEzXzgR_6-dieWnQ` | Seaglass Data |

## Troubleshooting

### "gcloud CLI not found"
gcloud isn't in PATH. In fish: `source ~/.config/fish/config.fish` or restart terminal.

### "Access blocked" on login
Add yourself as a test user in Google Cloud Console → APIs & Services → OAuth consent screen → Test users.

### "Google hasn't verified this app" warning
Expected for testing mode. Click "Continue" to proceed.

### Too many scopes error
Use `-s` flag to limit: `gws auth login -s drive,gmail,calendar,sheets`