Skip to main content

​
Command Structure

All gws commands follow a consistent structure: 
gws <service> <resource> <method> [flags]

​
Components

  • service: The Google Workspace API to use (e.g., drive, gmail, calendar)
  • resource: The API resource type (e.g., files, messages, events)
  • method: The operation to perform (e.g., list, create, update, delete)
  • flags: Optional parameters to customize the request

​
Examples

# List Drive files
gws drive files list --params '{"pageSize": 10}'

# Send a Gmail message
gws gmail users messages send --params '{"userId": "me"}' --json '{...}'

# Create a Calendar event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{...}'

​
Common Flags

These flags work across all commands:

​
--params

Pass query parameters and path parameters as JSON: 
gws drive files list --params '{"pageSize": 5, "orderBy": "modifiedTime desc"}'

​
--json

Provide the request body as JSON: 
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

​
--dry-run

Validate the request without sending it to the API: 
gws drive files create --json '{...}' --dry-run

​
--page-all

Automatically fetch all pages of results (output as NDJSON): 
gws drive files list --params '{"pageSize": 100}' --page-all

​
--page-limit

Limit the number of pages to fetch (default: 10): 
gws drive files list --page-all --page-limit 5

​
--page-delay

Set delay between page requests in milliseconds (default: 100): 
gws drive files list --page-all --page-delay 500

​
--format

Specify output format (json, table, yaml, csv): 
gws drive files list --format table

​
--upload

Upload a file with multipart request: 
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

​
--sanitize

Sanitize API responses through Model Armor: 
gws gmail users messages get --params '{...}' --sanitize "projects/P/locations/L/templates/T"

​
Using —help

Every command, resource, and method has built-in help: 
# Top-level help
gws --help

# Service help
gws drive --help

# Resource help
gws drive files --help

# Method help
gws drive files list --help

​
Dynamic Discovery

gws doesn’t ship with a static list of commands. It reads Google’s Discovery Service at runtime, so when Google adds new API endpoints or methods, gws picks them up automatically. To introspect any method’s schema: 
gws schema drive.files.list
gws schema gmail.users.messages.send --resolve-refs

​
Helper Commands

Some services include helper commands (prefixed with +) for common workflows:
  • Drive: +upload
  • Gmail: +send, +watch, +triage
  • Calendar: +insert
  • Sheets: +append, +read
  • Docs: +write
  • Chat: +send
Example: 
gws drive +upload ./report.pdf --parent FOLDER_ID
gws gmail +send --to user@example.com --subject "Hello" --body "Hi there!"
See individual service pages for complete helper command documentation.

​
Service Pages

Detailed command examples for each service:

Drive

Manage files, folders, and shared drives

Gmail

Send, read, and manage email

Calendar

Manage calendars and events

Sheets

Read and write spreadsheets

Docs

Read and write Google Docs

Chat

Manage Chat spaces and messages

Admin

Manage users, groups, and devices

All Services

Complete service reference table

​
Environment Variables

Control behavior with environment variables:
VariableDescription
GOOGLE_WORKSPACE_CLI_TOKENPre-obtained OAuth2 access token
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILEPath to credentials JSON
GOOGLE_WORKSPACE_CLI_IMPERSONATED_USERFor service account domain-wide delegation
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATEDefault Model Armor template
GOOGLE_WORKSPACE_CLI_SANITIZE_MODEwarn (default) or block
You can also use a .env file in your working directory.