google-workspace-cli

---
name: google-workspace-cli
description: Use when advising on Google Workspace administration or automation via the gws CLI — Gmail, Drive, Sheets, Calendar, Docs, Chat, Tasks setup, authentication, or security audits.
category: Engineering
version: 1.0.0
tools: []
---

# Google Workspace CLI

Guide Google Workspace administration and automation through the open-source `gws` CLI (github.com/googleworkspace/cli, Apache-2.0). The CLI builds its command surface dynamically from Google's Discovery Service, so it covers every supported Workspace API plus `+`-prefixed helper commands for common tasks.

**Verify before advising:** `gws` generates commands at runtime from Google's API discovery documents and the CLI is pre-v1.0, so command surfaces can shift between releases. When giving the user exact commands, tell them to confirm with `gws --help`, `gws <service> --help`, or `gws schema <service>.<resource>.<method>` against their installed version rather than trusting a remembered flag set.

## Installation

The user installs `gws` on their own machine via npm (Node.js 18+), Homebrew (macOS/Linux), Cargo (build from source), Nix, or a pre-built binary from the GitHub releases page. After installing, they confirm setup by checking the CLI's version and auth status.

## Authentication

- **Interactive OAuth:** the user creates a Google Cloud project and OAuth credentials, runs `gws auth setup` (which can use `gcloud` if available), then `gws auth login` scoped to only the services they need (e.g. `drive,gmail,sheets`) — always request minimal scopes.
- **Headless/CI:** export credentials from an already-authenticated interactive machine and point the CLI at the exported file via an environment variable, for service-account or automated contexts.
- **Key environment variables:** `GOOGLE_WORKSPACE_CLI_CLIENT_ID`, `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET`, `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`, `GOOGLE_WORKSPACE_CLI_TOKEN`, `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`, `GOOGLE_WORKSPACE_CLI_LOG`.
- OAuth tokens expire after 1 hour — long-running or scheduled scripts need re-auth handling.

## Workflow 1: Gmail Automation

Helper commands (`gws gmail +send`, `+reply`, `+forward`, `+triage`) cover send/reply/forward and an unread-inbox summary in a single call. For anything beyond the helpers — searching, labeling, filtering — use the discovery pattern `gws <service> <resource> <method>`, passing query/path parameters as JSON via `--params` and request bodies via `--json`. Always check the exact accepted parameters with `gws schema gmail.users.messages.list` (or the relevant method) before relying on a query like `from:x after:2025/01/01`. For bulk operations (e.g. archiving old read mail), preview with `--dry-run` first and paginate large result sets with `--page-all`, which streams one JSON line per page.

## Workflow 2: Drive & Sheets

List and inspect files via `drive files list`, upload via the `+upload` helper, and create spreadsheets via `sheets spreadsheets create`. Sharing and permission changes go through `drive permissions create`/`list` — always inspect the method schema first since permission grants are high-risk to get wrong (role, type, and email address must be exact). Sheets values can be read/appended via `+read`/`+append` helpers or the discovery methods `spreadsheets values get`/`update` for precise ranges.

## Workflow 3: Calendar & Meetings

Create events via the `+insert` helper or the `calendar.events.insert` discovery method; list upcoming events via `+agenda` (timezone-aware) or `calendar events list`. Finding open time across attendees uses the `calendar.freebusy.query` method with a time window and attendee list. Workflow helpers `+standup-report` and `+meeting-prep` compose these into higher-level briefings (today's meetings + tasks; prep for the next meeting).

## Workflow 4: Security Audit

Run a configuration/security audit across Gmail, Drive, Calendar, OAuth grants, and Admin settings, then review only the failing checks and their remediation before acting on them one at a time.

**Audit checks:**

| Area | Check | Risk |
|---|---|---|
| Drive | External sharing enabled | Data exfiltration |
| Gmail | Auto-forwarding rules | Data exfiltration |
| Gmail | DMARC/SPF/DKIM records | Email spoofing |
| Calendar | Default sharing visibility | Information leak |
| OAuth | Third-party app grants | Unauthorized access |
| Admin | Super admin count | Privilege escalation |
| Admin | 2-Step verification enforcement | Account takeover |

## Best Practices

**Security**
1. Use OAuth with minimal scopes — request only what each workflow needs
2. Store tokens in the system keyring, never in plain text files
3. Rotate service account keys every 90 days
4. Audit third-party OAuth app grants quarterly
5. Always dry-run before bulk destructive operations

**Automation**
1. `gws` output is structured JSON — filter/aggregate it downstream rather than eyeballing raw dumps
2. Prefer `gws workflow +*` helpers (multi-step, optimized) over hand-chaining raw API calls
3. `--page-all` streams one JSON line per page (NDJSON) for large result sets
4. Always preview with `--dry-run` before executing a request that changes state

**Performance**
1. Request only needed fields via the API's `fields` parameter to reduce payload size
2. Cap results with `pageSize` when browsing; use `--page-all` only for complete datasets
3. Prefer `+` helpers (single optimized calls) over multiple hand-chained API calls
4. Cache frequently accessed IDs (label IDs, folder IDs) rather than re-fetching

## Limitations

| Constraint | Impact |
|---|---|
| OAuth tokens expire after 1 hour | Re-auth needed for long-running scripts |
| API rate limits (per-user, per-service) | Bulk operations may hit 429 errors |
| Scope requirements vary by service | Must request correct scopes during auth |
| Pre-v1.0 CLI status | Breaking changes possible between releases |
| Google Cloud project required | Free, but requires setup in Cloud Console |
| Admin API needs admin privileges | Some audit checks require Workspace Admin role |

**Required scopes by service:**

| Service | Key Scopes |
|---|---|
| Gmail | `gmail.modify`, `gmail.send`, `gmail.labels` |
| Drive | `drive.file`, `drive.metadata.readonly` |
| Sheets | `spreadsheets` |
| Calendar | `calendar`, `calendar.events` |
| Admin | `admin.directory.user.readonly`, `admin.directory.group` |
| Tasks | `tasks` |