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  [--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   [sub-resource]  [flags]
gws  + [flags]
gws schema  [--resolve-refs]
gws auth 

Global Flags

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: viktorbezdek
• Source: viktorbezdek/skillstack
• License: MIT

Install and usage instructions live in the source repository linked above.