gws (Google Workspace CLI)
Website: https://github.com/googleworkspace/cli CLI Tool: gws Platform: Google Workspace
Description
gws is a powerful command-line interface for Google Workspace APIs. It provides direct access to Drive, Sheets, Gmail, Calendar, Docs, Slides, Tasks, People, Chat, Classroom, Forms, Keep, Meet, and more from the terminal.
Install
Prerequisites
Install Google Cloud CLI first:
# macOS
brew install --cask gcloud-cli
# Other platforms: https://cloud.google.com/sdk/docs/install
Install gws CLI
npm install -g @googleworkspace/cli
Authentication
# Set up auth (walks you through everything)
gws auth setup
# Login to your Google Workspace account
gws auth login
Usage Pattern
gws <service> <resource> [sub-resource] <method> [flags]
Services
| Service | Description |
|---|---|
drive |
Manage files, folders, and shared drives |
sheets |
Read and write spreadsheets |
gmail |
Send, read, and manage email |
calendar |
Manage calendars and events |
docs |
Read and write Google Docs |
slides |
Read and write presentations |
tasks |
Manage task lists and tasks |
people |
Manage contacts and profiles |
chat |
Manage Chat spaces and messages |
classroom |
Manage classes, rosters, and coursework |
forms |
Read and write Google Forms |
keep |
Manage Google Keep notes |
meet |
Manage Google Meet conferences |
admin-reports |
Audit logs and usage reports |
workflow |
Cross-service productivity workflows |
Examples
Google Drive
# List files (first 10)
gws drive files list --params '{"pageSize": 10}'
# Get a specific file
gws drive files get --params '{"fileId": "abc123"}'
# Upload a file
gws drive files create --upload ./document.pdf --params '{"name": "document.pdf"}'
Google Sheets
# Get spreadsheet
gws sheets spreadsheets get --params '{"spreadsheetId": "..."}'
# Read values from a range
gws sheets spreadsheets values get --params '{"spreadsheetId": "...", "range": "Sheet1!A1:D10"}'
# Update values
gws sheets spreadsheets values update --params '{"spreadsheetId": "...", "range": "A1"}' --json '{"values": [["Hello", "World"]]}'
Gmail
# List messages
gws gmail users messages list --params '{"userId": "me"}'
# Get a message
gws gmail users messages get --params '{"userId": "me", "id": "..."}'
# Send email
gws gmail users messages send --params '{"userId": "me"}' --json '{"raw": "..."}'
Google Calendar
# List calendars
gws calendar calendarList list
# List events
gws calendar events list --params '{"calendarId": "primary"}'
# Create event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{"summary": "Meeting", "start": {"dateTime": "2024-01-15T10:00:00Z"}, "end": {"dateTime": "2024-01-15T11:00:00Z"}}'
Flags
| Flag | Description |
|---|---|
--params <JSON> |
URL/Query parameters as JSON |
--json <JSON> |
Request body as JSON (POST/PATCH/PUT) |
--upload <PATH> |
Local file to upload as media content |
--output <PATH> |
Output file path for binary responses |
--format <FMT> |
Output format: json, table, yaml, csv |
--page-all |
Auto-paginate (NDJSON output) |
--page-limit <N> |
Max pages to fetch (default: 10) |
Schema Discovery
# View API schema for any method
gws schema drive.files.list
gws schema sheets.spreadsheets.values.get
gws schema gmail.users.messages.send
Environment Variables
| Variable | Description |
|---|---|
GOOGLE_WORKSPACE_CLI_TOKEN |
Pre-obtained OAuth2 access token |
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE |
Path to OAuth credentials JSON |
GOOGLE_WORKSPACE_CLI_CLIENT_ID |
OAuth client ID |
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET |
OAuth client secret |
GOOGLE_WORKSPACE_CLI_CONFIG_DIR |
Config directory (default: ~/.config/gws) |
Notes
- This is not an officially supported Google product
- Requires OAuth setup with appropriate Google Workspace scopes
- Use
gws schema <method>to discover available parameters for any API call
Comments (0)
Add a Comment
No comments yet. Be the first to comment!