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
1---2name: gws-cli3description: Google Workspace CLI (gws) for managing all 18 Workspace APIs from the terminal. Use when running gws commands, listing Drive files, sending Gmail, reading Sheets, creating Calendar events, managing Tasks, querying Chat, pushing Apps Script, building cross-service automations, or when user mentions gws or Google Workspace CLI. NOT for building MCP servers (use mcp-server), NOT for general API design (use api-design), NOT for GCP infrastructure (use cicd-pipelines).4---56# Google Workspace CLI (gws)78Single CLI for all 18 Google Workspace APIs. Commands built at runtime from Discovery Service.910## When to Use / Not Use1112**Use when:**13- Running any `gws` command or asking about Google Workspace operations14- Working with Drive, Gmail, Sheets, Calendar, Docs, Slides, Tasks, Chat, People, Forms, Keep, Meet, Classroom, Events, Apps Script, Admin Reports, Model Armor15- Building cross-service workflows (standup reports, meeting prep, email-to-task)16- Introspecting API schemas to discover valid parameters1718**Do NOT use when:**19- Building MCP servers -> use `mcp-server`20- General API design patterns -> use `api-design`21- GCP infrastructure (Compute Engine, Cloud Run) -> use `cicd-pipelines`2223## Decision Tree2425```26What Google Workspace operation do you need?27├── File/folder operations28│ ├── List/search files -> gws drive files list --params '{"q": "..."}'29│ ├── Upload file -> gws drive +upload ./file [--parent FOLDER_ID]30│ ├── Download/export -> gws drive files get --params '{"fileId": "ID", "alt": "media"}' --output ./file31│ └── Create folder -> gws drive files create --json '{"name": "X", "mimeType": "...folder"}'32├── Email33│ ├── Send email -> gws gmail +send --to X --subject Y --body Z34│ ├── Search inbox -> gws gmail users messages list --params '{"userId": "me", "q": "..."}'35│ ├── Reply/forward -> gws gmail +reply / +forward36│ └── Triage unread -> gws gmail +triage37├── Spreadsheets38│ ├── Read data -> gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'39│ ├── Append data -> gws sheets +append --spreadsheet ID --values "A,B,C"40│ ├── Write/overwrite -> gws sheets spreadsheets values update41│ └── REMEMBER: single-quote ranges ('Sheet1!A1:C10') to avoid bash ! expansion42├── Calendar43│ ├── View agenda -> gws calendar +agenda --today/--week44│ ├── Create event -> gws calendar +insert --summary X --start T --end T45│ └── With Meet link -> add --meet flag to +insert46├── Tasks47│ ├── List task lists -> gws tasks tasklists list48│ ├── Create task -> gws tasks tasks insert --params '{"tasklist": "ID"}' --json '{...}'49│ └── Complete task -> gws tasks tasks patch ... --json '{"status": "completed"}'50├── Chat51│ └── Send message -> gws chat +send --space ID --text "message"52├── Cross-service workflow53│ ├── Morning standup -> gws workflow +standup-report54│ ├── Meeting prep -> gws workflow +meeting-prep55│ ├── Email to task -> gws workflow +email-to-task --message-id ID56│ └── Weekly digest -> gws workflow +weekly-digest57├── Unknown parameters?58│ └── Introspect first -> gws schema <service.resource.method> [--resolve-refs]59└── Other service (Docs, Slides, People, Forms, Script, Reports, Meet, Keep, Classroom, Events, ModelArmor)60 └── See references/command-reference.md for full examples61```6263## Command Syntax6465```66gws <service> <resource> [sub-resource] <method> [flags]67gws <service> +<helper> [flags]68gws schema <service.resource.method> [--resolve-refs]69gws auth <login|status|export|logout|setup>70```7172## Global Flags7374| Flag | Short | Description | Default |75|---|---|---|---|76| `--params <JSON>` | -- | URL/query parameters as JSON | -- |77| `--json <JSON>` | -- | Request body as JSON | -- |78| `--upload <PATH>` | -- | File to upload (multipart) | -- |79| `--upload-content-type <MIME>` | -- | MIME type override for upload | auto-detect |80| `--output <PATH>` | `-o` | Save binary response to file | stdout |81| `--format <FMT>` | -- | `json`, `table`, `yaml`, `csv` | `json` |82| `--api-version <VER>` | -- | Override API version | service default |83| `--dry-run` | -- | Validate locally, don't send | false |84| `--sanitize <TEMPLATE>` | -- | Model Armor template for response | -- |85| `--page-all` | -- | Auto-paginate (NDJSON output) | off |86| `--page-limit <N>` | -- | Max pages with `--page-all` | 10 |87| `--page-delay <MS>` | -- | Delay between pages (ms) | 100 |8889## Services9091| Service | Aliases | Key Helpers |92|---|---|---|93| `drive` | -- | `+upload`, `files list/get/create/update/delete` |94| `gmail` | -- | `+send`, `+reply`, `+triage`, `+watch` |95| `sheets` | -- | `+read`, `+append` |96| `calendar` | -- | `+agenda`, `+insert` |97| `docs` | -- | `+write` |98| `slides` | -- | `presentations get/create/batchUpdate` |99| `tasks` | -- | `tasklists list`, `tasks insert/list/patch` |100| `people` | -- | `searchContacts`, `createContact` |101| `chat` | -- | `+send`, `spaces messages list/create` |102| `classroom` | -- | `courses list/students/courseWork` |103| `forms` | -- | `forms get`, `responses list` |104| `keep` | -- | `notes list/get` |105| `meet` | -- | `conferenceRecords list/participants` |106| `events` | -- | `+subscribe`, `+renew` |107| `admin-reports` | `reports` | `activities list` |108| `script` | -- | `+push`, `scripts run` |109| `modelarmor` | -- | `+sanitize-prompt`, `+sanitize-response`, `+create-template` |110| `workflow` | `wf` | `+standup-report`, `+meeting-prep`, `+email-to-task`, `+weekly-digest`, `+file-announce` |111112## Authentication113114```bash115gws auth setup # Interactive setup (requires gcloud CLI)116gws auth login # Opens browser for OAuth117gws auth login -s drive,gmail # Login with specific service scopes118gws auth login --readonly # Read-only scopes119gws auth login --full # All scopes including cloud-platform120gws auth status # Check credentials and scopes121```122123**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`124125**Credential storage:** AES-256-GCM encrypted at rest, key in OS keyring. Config dir: `~/.config/gws/`126127### Environment Variables128129| Variable | Description |130|---|---|131| `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained OAuth2 access token |132| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to credentials JSON |133| `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth client ID |134| `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth client secret |135| `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` | Override config directory |136| `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND` | `keyring` (default) or `file` |137| `GOOGLE_WORKSPACE_CLI_LOG` | Log level (e.g., `gws=debug`) |138| `GOOGLE_WORKSPACE_CLI_LOG_FILE` | JSON log file directory |139| `GOOGLE_WORKSPACE_CLI_PROJECT_ID` | GCP project ID override |140141## Schema Introspection142143```bash144gws schema drive.files.list # View method parameters and body schema145gws schema drive.files.list --resolve-refs # Resolve all $ref types inline146gws schema drive.File # View a specific type definition147```148149Use schema before constructing `--params` or `--json`, when a command fails, or for undocumented features.150151## Exit Codes152153| Code | Meaning |154|---|---|155| 0 | Success |156| 1 | API error (4xx/5xx) |157| 2 | Auth error (missing/expired credentials) |158| 3 | Validation error (bad args, unknown service) |159| 4 | Discovery error (can't fetch schema) |160| 5 | Internal error |161162## Anti-Patterns163164| Anti-Pattern | Problem | Solution |165|---|---|---|166| Missing `userId: "me"` in Gmail params | Gmail API requires userId; most common omission | Always include `"userId": "me"` in `--params` for Gmail methods |167| Double-quoting Sheets ranges | Bash expands `!` in double quotes as history expansion | Always single-quote: `'Sheet1!A1:C10'` |168| Forgetting `trashed = false` in Drive | `files.list` returns trashed files by default | Add `"q": "trashed = false"` unless you want trashed files |169| Binary download without `--output` | Binary content dumps to terminal (garbled) | Always add `--output ./file.pdf` for media downloads |170| 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"` |171| Guessing parameters instead of introspecting | Wrong param names cause exit code 3 | Run `gws schema <service.resource.method>` before constructing commands |172173## Common Errors174175| Error | Cause | Fix |176|---|---|---|177| `accessNotConfigured (403)` | API not enabled | Click `enable_url` in error output |178| `redirect_uri_mismatch` | Wrong OAuth client type | Recreate as "Desktop app" in Cloud Console |179| `Access blocked` | Test user not added | Add email under OAuth consent > Test users |180| Exit code 2 | Auth expired/missing | Run `gws auth login` |181| Exit code 3 | Bad params | Check `gws schema <method>` for valid params |182| Exit code 4 | Discovery fetch failed | Check network; retry (cached 24h) |183184## Version Override / Any Google API185186```bash187gws drive:v2 files list # Use Drive v2 instead of v3188gws youtube:v3 search list --params '...' # Access ANY Google API, not just 18 listed189```190191## Installation192193```bash194npm install -g @googleworkspace/cli # npm (recommended)195brew install googleworkspace-cli # Homebrew196cargo install --git https://github.com/googleworkspace/cli --locked # From source197gws --version # Verify198```199200**Prerequisites:** Google Cloud project with OAuth credentials (Desktop app type), OAuth consent screen with test users, APIs enabled for desired services.201202## Reference Directory203204| Topic | Reference |205|---|---|206| Per-service command examples (all 18 services) | `references/command-reference.md` |207| Authentication and setup details | `references/auth-and-setup.md` |208| Helper commands (+send, +reply, etc.) | `references/helper-commands.md` |209| Per-service query syntax | `references/query-syntax.md` |210| Daily workflow examples | `examples/daily-workflows.md` |211212## Integration213214- **mcp-server** -- Build MCP servers that expose gws operations as agent tools215- **workflow-automation** -- Orchestrate multi-step automations including Workspace operations216- **cicd-pipelines** -- Use gws in CI/CD for automated Workspace operations
viktorbezdek