Google CLI Tools
When does a Google Workspace operation belong in a CLI — and when does it belong in the UI?
Rule of thumb: if an agent workflow produces structured data that needs to land in Sheets, Drive, or Gmail — use the CLI. If a human is making one-off decisions in a document — use the UI.
What It Can Do
gws is a single CLI for all Google Workspace services. Pattern: gws <service> <resource> <method> [flags]
| Service | Operations |
|---|---|
sheets | Read/write/append spreadsheets and ranges |
drive | List, upload, download, share files |
gmail | Send, read, search, label messages |
calendar | List events, create meetings, check availability |
docs | Get document content, create docs |
chat | Send messages to Spaces |
Primary use case in agent workflows: Sheets — structured data in, structured data out. The other services support delivery (Drive upload, Gmail send) rather than data exchange.
When to Use CLI vs UI
| Situation | Use |
|---|---|
| Agent pipeline writes ROI model output to Sheets | CLI (gws sheets values update) |
| Human reviews and adjusts numbers in a sheet | UI |
| Agent uploads a PDF deliverable to a shared Drive folder | CLI (gws drive files create) |
| Human moves files between folders | UI |
| Agent sends a structured report email | CLI (gws gmail send) or transactional email service |
| Human replies to a client email | UI |
Auth Setup (one-time)
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/spreadsheets,\
https://www.googleapis.com/auth/drive,\
https://www.googleapis.com/auth/gmail.send
# Verify:
gws auth status
gws drive files list --params '{"pageSize": 3}'
Credentials are stored locally by gcloud — never committed to source control.
Core Operations
Sheets — Read
gws sheets spreadsheets values get \
--params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:Z50"}' \
--format csv
Sheets — Write
gws sheets spreadsheets values update \
--params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
--json '{"values": [["Label","Value"],["ROI","3.2x"]]}'
Sheets — Append Rows
gws sheets spreadsheets values append \
--params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1", "valueInputOption": "USER_ENTERED"}' \
--json '{"values": [["new row","data"]]}'
Drive — Upload File
gws drive files create \
--params '{"uploadType": "multipart"}' \
--upload ./report.pdf \
--json '{"name": "AI Transformation Report", "parents": ["FOLDER_ID"]}'
Drive — Share File
gws drive permissions create \
--params '{"fileId": "FILE_ID", "sendNotificationEmail": true}' \
--json '{"role": "reader", "type": "user", "emailAddress": "client@example.com"}'
Agent Delivery Pipeline Pattern
For workflows that produce a model, render a document, and deliver to a client:
1. Agent writes ROI model → Google Sheets (gws sheets values update)
2. Agent reads headline numbers → injects into report template
3. Report renders to PDF
4. gws drive files create → upload to shared folder
5. gws drive permissions create → share with client
OR
gws gmail send → email PDF directly
Schema Exploration
# Discover all parameters for any method:
gws schema sheets.spreadsheets.values.update
gws schema drive.files.create
gws schema gmail.users.messages.send
Anti-Patterns
| Anti-pattern | Fix |
|---|---|
| Passing full spreadsheet URL as ID | Strip to bare ID: everything between /d/ and /edit |
Using RAW for cells with formulas | Use USER_ENTERED — formulas need evaluation |
| One API call per cell for bulk writes | Use batchUpdate for 5+ ranges |
| Storing credentials in source control | Credentials live in ~/.config/gcloud/ — host-owned |
Using gws for interactive human decisions | CLI is for agent pipelines, not human editing sessions |
Context
- AI CLI Tools — Other CLI tools in the agent workflow stack
- Agent Workflows — Where this fits in the broader automation pipeline
- Data Pipelines — Structured data patterns for agent output
Links
Questions
When does putting structured agent output into Google Sheets create more friction than it removes?
- At what data volume does a direct Sheets write become a bottleneck — and what replaces it?
- Which
gwsoperation is most likely to fail silently in an agent pipeline — and how do you detect it? - How does this pattern change when the consumer of the Sheet is another agent rather than a human?