google-sheets

name: google-sheets description: "Google Sheets: Read, write, and manage spreadsheets via the gws CLI. Use when reading cell ranges, appending rows, creating spreadsheets, or performing batch updates."

Google Sheets

Read and write spreadsheets using the gws CLI.

Setup

Run once before first use:

# Install gws (macOS Apple Silicon)
curl -fsSL https://github.com/googleworkspace/cli/releases/latest/download/gws-darwin-arm64.tar.gz | tar xz
sudo mv gws /usr/local/bin/

# Authenticate (opens browser)
gws auth setup        # first time: creates GCP project, enables APIs, logs in
gws auth login -s sheets   # subsequent logins (select only Sheets scopes)

If gws auth setup fails (requires gcloud), follow the manual OAuth setup:

1. Create a Desktop OAuth client at https://console.cloud.google.com/apis/credentials
2. Download JSON to ~/.config/gws/client_secret.json
3. Add yourself as a test user in the OAuth consent screen
4. Run gws auth login

Helper Commands

+read — Read values from a spreadsheet

gws sheets +read --spreadsheet <ID> --range <RANGE>

gws sheets +read --spreadsheet SPREADSHEET_ID --range "Sheet1!A1:D10"
gws sheets +read --spreadsheet SPREADSHEET_ID --range Sheet1

Read-only.

+append — Append rows to a spreadsheet

gws sheets +append --spreadsheet <ID>

gws sheets +append --spreadsheet ID --values 'Alice,100,true'
gws sheets +append --spreadsheet ID --json-values '[["a","b"],["c","d"]]'
gws sheets +append --spreadsheet ID --range "Sheet2!A1" --values 'Alice,100'

Use --values for simple single-row appends. Use --json-values for bulk multi-row inserts.

Write command — confirm with the user before executing.

Raw API

gws sheets <resource> <method> --params '{"key": "val"}' --json '{"key": "val"}'

Common operations

Create a spreadsheet:

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

Get spreadsheet metadata:

gws sheets spreadsheets get --params '{"spreadsheetId": "SPREADSHEET_ID"}'

Read cell values:

gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

Write cell values:

gws sheets spreadsheets values update \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95], ["Bob", 87]]}'

Append rows (raw API):

gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Charlie", 92]]}'

Clear a range:

gws sheets spreadsheets values clear \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

Batch update (add a sheet, formatting, etc.):

gws sheets spreadsheets batchUpdate --params '{"spreadsheetId": "SPREADSHEET_ID"}' \
  --json '{"requests": [{"addSheet": {"properties": {"title": "New Tab"}}}]}'

Write/delete commands — confirm with the user before executing.

Shell Tips

Sheets ranges use ! which zsh interprets as history expansion. Always use double quotes around range values:

# Correct
gws sheets +read --spreadsheet ID --range "Sheet1!A1:D10"

# Wrong (zsh will mangle the !)
gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'

Wrap --params and --json values in single quotes so the shell doesn't interpret inner double quotes:

gws sheets spreadsheets values get --params '{"spreadsheetId": "ID", "range": "Sheet1!A1:C10"}'

Global Flags

Pagination

Discovering Methods

gws sheets --help                              # list all resources and methods
gws schema sheets.spreadsheets.values.get      # inspect params, types, defaults
gws schema sheets.spreadsheets.values.update   # inspect request body schema
gws schema sheets.spreadsheets.batchUpdate     # inspect batch update requests

Security Rules

• Never output secrets (API keys, tokens) directly
• Always confirm with user before write/delete commands
• Prefer --dry-run for destructive operations