google-workspace-cli

What this skill does

# Google Workspace CLI (`gws`)

One CLI for **all** of Google Workspace — Drive, Gmail, Calendar, Sheets, Docs, Slides, Chat, Tasks, Admin, Meet, Forms, Keep, and every other Workspace API. Built for humans and AI agents. Structured JSON output. 100+ agent skills included.

> **Note:** This is not an officially supported Google product.

> **Important:** This project is under active development. Expect breaking changes as we march toward v1.0.

**Repository:** https://github.com/googleworkspace/cli

## How It Works

`gws` does NOT ship a static list of commands. It reads Google's own [Discovery Service](https://developers.google.com/discovery) at runtime and builds its entire command surface dynamically. When Google adds a new API endpoint or method, `gws` picks it up automatically — zero updates needed.

## Prerequisites

- **Node.js 18+** — for `npm install` (or download a pre-built binary from [GitHub Releases](https://github.com/googleworkspace/cli/releases))
- **A Google Cloud project** — required for OAuth credentials. You can create one via the [Google Cloud Console](https://console.cloud.google.com/), with the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install), or with the `gws auth setup` command.
- **A Google account** with access to Google Workspace

## Installation

```bash
# Install globally via npm (recommended — bundles native binaries, no Rust needed)
npm install -g @googleworkspace/cli

# Verify installation
gws --version
```

Alternative installation methods:
```bash
# From GitHub Releases (pre-built binaries)
# Download from: https://github.com/googleworkspace/cli/releases

# Build from source (requires Rust toolchain)
cargo install --git https://github.com/googleworkspace/cli --locked

# Nix flake
nix run github:googleworkspace/cli
```

## Quick Start

```bash
gws auth setup     # walks you through Google Cloud project config
gws auth login     # subsequent OAuth login
gws drive files list --params '{"pageSize": 5}'
```

## Authentication

### Which setup should I use?

| I have… | Use |
|:--------|:----|
| `gcloud` installed and authenticated | `gws auth setup` (fastest — one command) |
| A GCP project but no `gcloud` | Manual OAuth setup in Cloud Console |
| An existing OAuth access token | `GOOGLE_WORKSPACE_CLI_TOKEN` env var |
| Existing credentials JSON (service account or exported) | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` env var |

### Quick Setup (recommended — requires gcloud CLI)

```bash
gws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in
gws auth login       # subsequent logins with scope selection
```

> Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring.

### Scoped Login (for unverified/testing OAuth apps, limited to ~25 scopes)

> **Warning:** Unverified (testing-mode) apps are limited to ~25 OAuth scopes. The `recommended` scope preset includes 85+ scopes and **will fail** for unverified apps (especially for `@gmail.com` accounts). Choose individual services instead:

```bash
# Select only the services you need to stay under the scope limit
gws auth login -s drive,gmail,sheets
gws auth login --scopes drive,gmail,calendar,docs,chat
```

### Multiple Accounts

```bash
gws auth login --account [email protected]
gws auth login --account [email protected]

gws auth list                                    # list registered accounts
gws auth default [email protected]                   # set the default

gws --account [email protected] drive files list  # one-off override
export [email protected]  # env var override
```

Credentials are stored per-account as `credentials.<b64-email>.enc` in `~/.config/gws/`, with an `accounts.json` registry tracking defaults.

### Manual OAuth Setup (no gcloud)

Use this when `gws auth setup` cannot automate project/client creation, or when you want explicit control.

1. Open Google Cloud Console in the target project:
   - OAuth consent screen: `https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>`
   - Credentials: `https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>`
2. Configure OAuth branding/audience if prompted — App type: **External** (testing mode is fine)
3. Add your account under **Test users**
4. Create an OAuth client — Type: **Desktop app**
5. Download the client JSON → save to `~/.config/gws/client_secret.json`

> **Important:** You must add yourself as a test user. In the OAuth consent screen, click **Test users → Add users** and enter your Google account email. Without this, login will fail with a generic "Access blocked" error.

Then run:
```bash
gws auth login
```

### Headless / CI

```bash
# On a machine with a browser:
gws auth export --unmasked > credentials.json

# On the headless machine:
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list   # just works
```

### Service Account (server-to-server)

```bash
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

# For Domain-Wide Delegation:
export [email protected]
```

### Pre-obtained Access Token

```bash
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
```

### Browser-Assisted Auth (for AI agents)

Agents can complete OAuth with browser automation:

- **Human flow:** Run `gws auth login`, open the printed URL, approve scopes.
- **Agent-assisted flow:** The agent opens the URL, selects the account, handles consent prompts, and returns control once the localhost callback succeeds.

If consent shows "Google hasn't verified this app" (testing mode), click **Continue**. If scope checkboxes appear, select required scopes (or **Select all**) before continuing.

### Auth Precedence

| Priority | Method | Source |
|:---------|:-------|:-------|
| 1 | Access token | `GOOGLE_WORKSPACE_CLI_TOKEN` |
| 2 | Credentials file | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` |
| 3 | Per-account encrypted credentials | `gws auth login --account EMAIL` |
| 4 | Plaintext credentials | `~/.config/gws/credentials.json` |

Account resolution: `--account` flag > `GOOGLE_WORKSPACE_CLI_ACCOUNT` env var > default in `accounts.json`.

> All environment variables can also live in a `.env` file in your project root.

## Command Structure

The universal pattern for ALL gws commands:

```
gws <service> <resource> <method> [--params '{ JSON }'] [--json '{ JSON }'] [flags]
```

### Global Flags

| Flag | Description |
|:-----|:------------|
| `--help` | Show help for any service, resource, or method |
| `--params '{ JSON }'` | URL/query parameters as JSON |
| `--json '{ JSON }'` | Request body as JSON |
| `--dry-run` | Preview the HTTP request without executing |
| `--page-all` | Auto-paginate, one JSON line per page (NDJSON) |
| `--page-limit <N>` | Max pages to fetch (default: 10) |
| `--page-delay <MS>` | Delay between pages (default: 100ms) |
| `--upload <path>` | Multipart file upload |
| `--account <email>` | Use a specific authenticated account |
| `--sanitize <template>` | Model Armor response sanitization |

### Introspecting Schemas

```bash
# See the full request/response schema for any method
gws schema drive.files.list
gws schema gmail.users.messages.send
gws schema calendar.events.insert
```

## Core Services — Commands & Examples

### Google Drive

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

# List ALL files (auto-paginate as NDJSON)
gws drive files list --params '{"pageSize": 100}' --page-all

# Search for files
gws drive files list --params '{"q": "name contains '\''report'\'' and mimeType = '\''application/pdf'\''", "pageSize": 20}'

# Get file metadata
gws drive files get --params '{"fileId": "FILE_ID"}'

# Upload a file
gws drive files create --json '{"name": "report.pdf", "parents": ["FOLDER_ID"]}' --upload ./report.pdf

# Create a folder
gws drive files create --json '{"name": "Project Docs", "mimeType": "app