Google Workspace CLI

Use gws for Google Workspace automation from the shell: authentication, API discovery, bounded reads, and verified writes across Drive, Docs, Sheets, Gmail, Calendar, and Chat. Prefer the CLI for supported operations; use a connected app when the requested native editing operation needs its document context or capabilities.

Workflow

1. Resolve the profile: check gws auth status for the account and scopes without printing credentials. Set GOOGLE_WORKSPACE_CLI_CONFIG_DIR before auth commands to isolate profiles; an existing GOOGLE_WORKSPACE_CLI_TOKEN or GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE can override stored credentials, so verify the effective identity without echoing those values. gws also loads unset variables from a .env in the working directory or any parent, so a project file can switch accounts: run gws, including the draft-doc and draft-mail scripts, from a directory with no .env in its path (such as the scratchpad) and check user there before writing.

2. Inspect the installed command and live schema: use <command> --help for flags and schema for the API contract. Start without recursive reference expansion; inspect a referenced type separately when needed.

   gws schema <service.resource.method>
   gws schema <service.TypeName>

3. Start with a bounded read: pass identifiers, filters, and only the needed fields and date range through --params; use --page-all --page-limit <n> only when every page is needed. It emits NDJSON with one object per page, not one JSON array; keep nextPageToken (and Drive incompleteSearch) in fields, because reaching --page-limit with a remaining token means the result is incomplete.

   gws drive files list --params '{"pageSize":10,"q":"trashed = false","fields":"nextPageToken,incompleteSearch,files(id,name,mimeType)"}' --format json

4. Choose the content path: read service recipes for metadata versus bodies, Docs tabs, Sheets ranges, Gmail MIME/replies, Calendar times, Slides and Drive exports. Prefer a +helper listed by gws <service> --help when its documented semantics match the request.
5. Prepare writes exactly: resolve the service, stable identifiers or ranges, content, recipients, and sharing effects first. Follow file-based requests to serialize multiline content, separate --params from --json, and inspect a --dry-run. It validates request construction, not permissions or server acceptance. For Chat, follow formatting and threads before composing text.
6. Write with authority: reuse authority already supplied by the user for the intended create or edit; ask only for missing consequential scope, using the one-off grants in dot-cli authentication. Sending mail or Chat, destructive changes, and permission changes require explicit authority. Prepare the concrete request before asking for missing approval.
7. Apply the smallest call: no broad search followed by an unreviewed batch mutation; keep retries idempotent with stable request identifiers or a read-before-write guard where the API supports them.
8. Verify by reading back: fetch the changed resource and compare the requested fields; for messages and events, separate accepted API state from recipient-visible delivery.

Task guides

• cli-details: Use local Workspace helpers and diagnose CLI authentication, schema, pagination, or request failures.

Official Skills

Upstream: googleworkspace/cli skills, which generates a shared base skill plus one selection per API. Discover with DISABLE_TELEMETRY=1 skills add googleworkspace/cli --list. Follow the shared vendor-skill policy and include the base dependency required by the chosen service.

Documentation

• Google Workspace CLI · Workspace API reference
• Releases: Workspace CLI · changelog
• Companion skills: draft-doc (Google Docs: native .md for living docs, .gdoc for styled deliverables), draft-mail (draft-only email and replies), acli (same authority rules for Atlassian), gcloud (Google Cloud), mcp-setup (connected apps).