# 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)

```bash
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)

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

## Get Spreadsheet Metadata (sheet names, grid size)

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

Useful to discover sheet names before reading/writing.

## Add a New Sheet Tab

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

## Delete a Sheet Tab

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

## Rename a Sheet Tab

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

## Auto-resize Columns

```bash
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)

```bash
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

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