claude-configs/skills/gws/examples-sheets.md

GWS Sheets Examples & Reference

Load when working with Google Sheets. Contains verbose JSON shapes and less common patterns.

Batch Update (write to multiple ranges at once)

gws sheets spreadsheets values batchUpdate \
  --params "{\"spreadsheetId\": \"$ID\", \"valueInputOption\": \"USER_ENTERED\"}" \
  --json '{
    "data": [
      {"range": "Sheet1\u0021A1:C1", "values": [["Header1", "Header2", "Header3"]]},
      {"range": "Sheet1\u0021A2:C4", "values": [
        ["row1a", "row1b", "row1c"],
        ["row2a", "row2b", "row2c"],
        ["row3a", "row3b", "row3c"]
      ]}
    ]
  }'

Batch Get (read multiple ranges at once)

gws sheets spreadsheets values batchGet \
  --params "{\"spreadsheetId\": \"$ID\", \"ranges\": [\"Sheet1\u0021A1:C1\", \"Sheet1\u0021A5:C10\"]}"

Get Spreadsheet Metadata (sheet names, grid size)

gws sheets spreadsheets get \
  --params "{\"spreadsheetId\": \"$ID\", \"includeGridData\": false}"

Useful to discover sheet names before reading/writing.

Add a New Sheet Tab

gws sheets spreadsheets batchUpdate \
  --params "{\"spreadsheetId\": \"$ID\"}" \
  --json '{
    "requests": [
      {"addSheet": {"properties": {"title": "NewTab", "index": 1}}}
    ]
  }'

Delete a Sheet Tab

# Get the sheetId first from spreadsheets get, then:
gws sheets spreadsheets batchUpdate \
  --params "{\"spreadsheetId\": \"$ID\"}" \
  --json '{
    "requests": [
      {"deleteSheet": {"sheetId": 123456789}}
    ]
  }'

Rename a Sheet Tab

gws sheets spreadsheets batchUpdate \
  --params "{\"spreadsheetId\": \"$ID\"}" \
  --json '{
    "requests": [
      {"updateSheetProperties": {
        "properties": {"sheetId": 0, "title": "Draft Board"},
        "fields": "title"
      }}
    ]
  }'

Auto-resize Columns

gws sheets spreadsheets batchUpdate \
  --params "{\"spreadsheetId\": \"$ID\"}" \
  --json '{
    "requests": [
      {"autoResizeDimensions": {
        "dimensions": {
          "sheetId": 0,
          "dimension": "COLUMNS",
          "startIndex": 0,
          "endIndex": 10
        }
      }}
    ]
  }'

Format Header Row (bold, background color)

gws sheets spreadsheets batchUpdate \
  --params "{\"spreadsheetId\": \"$ID\"}" \
  --json '{
    "requests": [
      {
        "repeatCell": {
          "range": {"sheetId": 0, "startRowIndex": 0, "endRowIndex": 1},
          "cell": {
            "userEnteredFormat": {
              "backgroundColor": {"red": 0.2, "green": 0.4, "blue": 0.8},
              "textFormat": {"bold": true, "foregroundColor": {"red": 1, "green": 1, "blue": 1}}
            }
          },
          "fields": "userEnteredFormat(backgroundColor,textFormat)"
        }
      }
    ]
  }'

Freeze Header Row

gws sheets spreadsheets batchUpdate \
  --params "{\"spreadsheetId\": \"$ID\"}" \
  --json '{
    "requests": [
      {"updateSheetProperties": {
        "properties": {
          "sheetId": 0,
          "gridProperties": {"frozenRowCount": 1}
        },
        "fields": "gridProperties.frozenRowCount"
      }}
    ]
  }'