Google Sheets (gws-sheets)

PREREQUISITE: Read the gws-shared skill for auth, global flags, and security rules.

Read and write Google Sheets spreadsheets using the gws CLI.

gws sheets <resource> <method> [flags]

Shell tip: Sheet ranges contain ! which zsh interprets as history expansion. Always use double quotes around range values:

--range "Sheet1!A1:D10"   # CORRECT
--range 'Sheet1!A1:D10'   # WRONG in zsh

Quick Examples

# Create a new spreadsheet
gws sheets spreadsheets create \
  --json '{"properties": {"title": "Q1 Budget 2026"}}'

# Get spreadsheet metadata
gws sheets spreadsheets get \
  --params '{"spreadsheetId": "SPREADSHEET_ID"}'

# Read a range of cells
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:E10"}'

# Write values to a range
gws sheets spreadsheets values update \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Email", "Amount"], ["Alice", "alice@example.com", 500]]}'

# Append rows to a sheet
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED", "insertDataOption": "INSERT_ROWS"}' \
  --json '{"values": [["Bob", "bob@example.com", 750]]}'

# Clear a range
gws sheets spreadsheets values clear \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A2:E100"}'

# Batch read multiple ranges
gws sheets spreadsheets values batchGet \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "ranges": ["Sheet1!A1:B10", "Sheet2!C1:D5"]}'

# Batch write multiple ranges
gws sheets spreadsheets values batchUpdate \
  --params '{"spreadsheetId": "SPREADSHEET_ID"}' \
  --json '{
    "valueInputOption": "USER_ENTERED",
    "data": [
      {"range": "Sheet1!A1", "values": [["Header"]]},
      {"range": "Sheet2!A1", "values": [["Other Header"]]}
    ]
  }'

# Add a new sheet tab
gws sheets spreadsheets batchUpdate \
  --params '{"spreadsheetId": "SPREADSHEET_ID"}' \
  --json '{
    "requests": [{"addSheet": {"properties": {"title": "April"}}}]
  }'

# Format cells (bold header row)
gws sheets spreadsheets batchUpdate \
  --params '{"spreadsheetId": "SPREADSHEET_ID"}' \
  --json '{
    "requests": [{
      "repeatCell": {
        "range": {"sheetId": 0, "startRowIndex": 0, "endRowIndex": 1},
        "cell": {"userEnteredFormat": {"textFormat": {"bold": true}}},
        "fields": "userEnteredFormat.textFormat.bold"
      }
    }]
  }'

Helper Commands

Command	Description
gws sheets +read	Read values from a spreadsheet (simplified)
gws sheets +append	Append a row to a spreadsheet (simplified)

valueInputOption Reference

Value	Behaviour
RAW	Values stored as-is (strings stay strings)
USER_ENTERED	Parsed as if typed by a user (formulas evaluated, dates recognised)

Key API Resources

spreadsheets

get, create, batchUpdate

spreadsheets.values

get, update, append, clear, batchGet, batchUpdate, batchClearByDataFilter

spreadsheets.sheets

copyTo

Discovering More

gws sheets --help
gws schema sheets.spreadsheets.values.get
gws schema sheets.spreadsheets.values.append
gws schema sheets.spreadsheets.batchUpdate