Gws cli

Google Workspace CLI (gws)

Single CLI for all 18 Google Workspace APIs. Commands built at runtime from Discovery Service.

When to Use / Not Use

Use when:

• Running any gws command or asking about Google Workspace operations
• Working with Drive, Gmail, Sheets, Calendar, Docs, Slides, Tasks, Chat, People, Forms, Keep, Meet, Classroom, Events, Apps Script, Admin Reports, Model Armor
• Building cross-service workflows (standup reports, meeting prep, email-to-task)
• Introspecting API schemas to discover valid parameters

Do NOT use when:

• Building MCP servers -> use mcp-server
• General API design patterns -> use api-design
• GCP infrastructure (Compute Engine, Cloud Run) -> use cicd-pipelines

Decision Tree

What Google Workspace operation do you need?
├── File/folder operations
│   ├── List/search files -> gws drive files list --params '{"q": "..."}'
│   ├── Upload file -> gws drive +upload ./file [--parent FOLDER_ID]
│   ├── Download/export -> gws drive files get --params '{"fileId": "ID", "alt": "media"}' --output ./file
│   └── Create folder -> gws drive files create --json '{"name": "X", "mimeType": "...folder"}'
├── Email
│   ├── Send email -> gws gmail +send --to X --subject Y --body Z
│   ├── Search inbox -> gws gmail users messages list --params '{"userId": "me", "q": "..."}'
│   ├── Reply/forward -> gws gmail +reply / +forward
│   └── Triage unread -> gws gmail +triage
├── Spreadsheets
│   ├── Read data -> gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'
│   ├── Append data -> gws sheets +append --spreadsheet ID --values "A,B,C"
│   ├── Write/overwrite -> gws sheets spreadsheets values update
│   └── REMEMBER: single-quote ranges ('Sheet1!A1:C10') to avoid bash ! expansion
├── Calendar
│   ├── View agenda -> gws calendar +agenda --today/--week
│   ├── Create event -> gws calendar +insert --summary X --start T --end T
│   └── With Meet link -> add --meet flag to +insert
├── Tasks
│   ├── List task lists -> gws tasks tasklists list
│   ├── Create task -> gws tasks tasks insert --params '{"tasklist": "ID"}' --json '{...}'
│   └── Complete task -> gws tasks tasks patch ... --json '{"status": "completed"}'
├── Chat
│   └── Send message -> gws chat +send --space ID --text "message"
├── Cross-service workflow
│   ├── Morning standup -> gws workflow +standup-report
│   ├── Meeting prep -> gws workflow +meeting-prep
│   ├── Email to task -> gws workflow +email-to-task --message-id ID
│   └── Weekly digest -> gws workflow +weekly-digest
├── Unknown parameters?
│   └── Introspect first -> gws schema <service.resource.method> [--resolve-refs]
└── Other service (Docs, Slides, People, Forms, Script, Reports, Meet, Keep, Classroom, Events, ModelArmor)
    └── See references/command-reference.md for full examples

Command Syntax

gws <service> <resource> [sub-resource] <method> [flags]
gws <service> +<helper> [flags]
gws schema <service.resource.method> [--resolve-refs]
gws auth <login|status|export|logout|setup>

Global Flags

Flag	Short	Description	Default
--params <JSON>	--	URL/query parameters as JSON	--
--json <JSON>	--	Request body as JSON	--
--upload <PATH>	--	File to upload (multipart)	--
--upload-content-type <MIME>	--	MIME type override for upload	auto-detect
--output <PATH>	-o	Save binary response to file	stdout
--format <FMT>	--	json, table, yaml, csv	json
--api-version <VER>	--	Override API version	service default
--dry-run	--	Validate locally, don't send	false
--sanitize <TEMPLATE>	--	Model Armor template for response	--
--page-all	--	Auto-paginate (NDJSON output)	off
--page-limit <N>	--	Max pages with --page-all	10
--page-delay <MS>	--	Delay between pages (ms)	100

Services

Service	Aliases	Key Helpers
drive	--	+upload, files list/get/create/update/delete
gmail	--	+send, +reply, +triage, +watch
sheets	--	+read, +append
calendar	--	+agenda, +insert
docs	--	+write
slides	--	presentations get/create/batchUpdate
tasks	--	tasklists list, tasks insert/list/patch
people	--	searchContacts, createContact
chat	--	+send, spaces messages list/create
classroom	--	courses list/students/courseWork
forms	--	forms get, responses list
keep	--	notes list/get
meet	--	conferenceRecords list/participants
events	--	+subscribe, +renew
admin-reports	reports	activities list
script	--	+push, scripts run
modelarmor	--	+sanitize-prompt, +sanitize-response, +create-template
workflow	wf	+standup-report, +meeting-prep, +email-to-task, +weekly-digest, +file-announce

Authentication

gws auth setup                    # Interactive setup (requires gcloud CLI)
gws auth login                    # Opens browser for OAuth
gws auth login -s drive,gmail     # Login with specific service scopes
gws auth login --readonly         # Read-only scopes
gws auth login --full             # All scopes including cloud-platform
gws auth status                   # Check credentials and scopes

Auth precedence (highest to lowest): GOOGLE_WORKSPACE_CLI_TOKEN env -> GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE env -> encrypted credentials from gws auth login -> plaintext ~/.config/gws/credentials.json

Credential storage: AES-256-GCM encrypted at rest, key in OS keyring. Config dir: ~/.config/gws/

Environment Variables

Variable	Description
GOOGLE_WORKSPACE_CLI_TOKEN	Pre-obtained OAuth2 access token
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE	Path to credentials JSON
GOOGLE_WORKSPACE_CLI_CLIENT_ID	OAuth client ID
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET	OAuth client secret
GOOGLE_WORKSPACE_CLI_CONFIG_DIR	Override config directory
GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND	keyring (default) or file
GOOGLE_WORKSPACE_CLI_LOG	Log level (e.g., gws=debug)
GOOGLE_WORKSPACE_CLI_LOG_FILE	JSON log file directory
GOOGLE_WORKSPACE_CLI_PROJECT_ID	GCP project ID override

Schema Introspection

gws schema drive.files.list              # View method parameters and body schema
gws schema drive.files.list --resolve-refs  # Resolve all $ref types inline
gws schema drive.File                    # View a specific type definition

Use schema before constructing --params or --json, when a command fails, or for undocumented features.

Exit Codes

Code	Meaning
0	Success
1	API error (4xx/5xx)
2	Auth error (missing/expired credentials)
3	Validation error (bad args, unknown service)
4	Discovery error (can't fetch schema)
5	Internal error

Anti-Patterns

Anti-Pattern	Problem	Solution
Missing userId: "me" in Gmail params	Gmail API requires userId; most common omission	Always include "userId": "me" in --params for Gmail methods
Double-quoting Sheets ranges	Bash expands ! in double quotes as history expansion	Always single-quote: 'Sheet1!A1:C10'
Forgetting trashed = false in Drive	files.list returns trashed files by default	Add "q": "trashed = false" unless you want trashed files
Binary download without --output	Binary content dumps to terminal (garbled)	Always add --output ./file.pdf for media downloads
Missing Chat API scope	403 on chat commands even after auth	Chat requires explicit scope: gws auth login --scopes "https://www.googleapis.com/auth/chat.messages"
Guessing parameters instead of introspecting	Wrong param names cause exit code 3	Run gws schema <service.resource.method> before constructing commands

Common Errors

Error	Cause	Fix
accessNotConfigured (403)	API not enabled	Click enable_url in error output
redirect_uri_mismatch	Wrong OAuth client type	Recreate as "Desktop app" in Cloud Console
Access blocked	Test user not added	Add email under OAuth consent > Test users
Exit code 2	Auth expired/missing	Run gws auth login
Exit code 3	Bad params	Check gws schema <method> for valid params
Exit code 4	Discovery fetch failed	Check network; retry (cached 24h)

Version Override / Any Google API

gws drive:v2 files list                    # Use Drive v2 instead of v3
gws youtube:v3 search list --params '...'  # Access ANY Google API, not just 18 listed

Installation

npm install -g @googleworkspace/cli        # npm (recommended)
brew install googleworkspace-cli            # Homebrew
cargo install --git https://github.com/googleworkspace/cli --locked  # From source
gws --version                              # Verify

Prerequisites: Google Cloud project with OAuth credentials (Desktop app type), OAuth consent screen with test users, APIs enabled for desired services.

Reference Directory

Topic	Reference
Per-service command examples (all 18 services)	references/command-reference.md
Authentication and setup details	references/auth-and-setup.md
Helper commands (+send, +reply, etc.)	references/helper-commands.md
Per-service query syntax	references/query-syntax.md
Daily workflow examples	examples/daily-workflows.md

Integration

• mcp-server -- Build MCP servers that expose gws operations as agent tools
• workflow-automation -- Orchestrate multi-step automations including Workspace operations
• cicd-pipelines -- Use gws in CI/CD for automated Workspace operations