GWS Sheets Streamlined

Streamlined command for Google Sheets operations including reading, writing, appending rows, creating spreadsheets, and executing batch updates through the GWS CLI.

When to Use This Command

Run this command when you need to interact with Google Sheets programmatically -- reading data, appending rows, or performing batch operations.

• You need to read cell ranges from a Google Spreadsheet using the +read helper
• You want to append new rows of data to an existing sheet using the +append helper
• You are creating new spreadsheets or performing batch updates on existing ones
• You need to extract data from spreadsheets for reporting or pipeline processing

Use it also when:

• You want to use developer metadata to tag and filter spreadsheet data
• You need to paginate through large spreadsheet datasets

Quick Start

Copy
# .claude/commands/gws-sheets-streamlined.md
name: gws-sheets-streamlined
description: Streamlined Google Sheets read, write, and batch operations
arguments:
  operation: The Sheets operation to execute

Copy
# Read values from a spreadsheet range
claude gws-sheets-streamlined "+read --spreadsheet-id 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms --range 'Sheet1!A1:D10'"

Expected output:
{
  "range": "Sheet1!A1:D10",
  "values": [
    ["Name", "Email", "Role", "Status"],
    ["Alice", "[email protected]", "Engineer", "Active"],
    ["Bob", "[email protected]", "Designer", "Active"]
  ]
}

Core Concepts

Concept	Description
Spreadsheet ID	The unique identifier from the spreadsheet URL
Range	Cell reference like Sheet1!A1:D10 or named range
Batch Update	Multiple operations applied atomically to a spreadsheet
Append	Add rows after the last row of data in a sheet
Values Resource	The API resource for reading and writing cell values

Sheets Data Flow:
  ┌─────────┐     ┌──────────────┐     ┌───────────┐
  │ +read   │────>│ Sheets API   │<────│ +append   │
  └─────────┘     │   (v4)       │     └───────────┘
                  │              │
  ┌─────────────┐ │              │ ┌──────────────────┐
  │ batchUpdate │>│              │<│ create           │
  └─────────────┘ └──────────────┘ └──────────────────┘

Configuration

Parameter	Default	Description
spreadsheet-id	required	The target spreadsheet identifier
range	required	Cell range in A1 notation or named range
format	json	Output format: json, table, yaml, csv
page-all	false	Auto-paginate through large result sets
dry-run	false	Validate the operation without executing

Best Practices

1. Use the +read and +append helpers for common operations -- These shortcuts handle parameter construction automatically, reducing the chance of errors compared to raw API calls.

2. Specify precise ranges to minimize data transfer -- Instead of reading entire sheets, target specific ranges like A1:D100 to reduce response size and latency.

3. Use batchUpdate for multiple changes -- When you need to make several modifications (formatting, cell values, sheet properties), bundle them in a single batchUpdate call.

4. Include the sheet name in ranges -- Always prefix ranges with the sheet name (Sheet1!A1:B5) to avoid ambiguity, especially in spreadsheets with multiple tabs.

5. Handle empty cells gracefully -- The Sheets API omits trailing empty cells in rows. Pad your data processing logic to account for variable-length row arrays.

Common Issues

1. Spreadsheet not found (404) -- Verify the spreadsheet ID is correct and that the authenticated user has at least viewer access to the spreadsheet.

2. Range does not exist -- Sheet names are case-sensitive and must match exactly. Use gws sheets spreadsheets get to list available sheets before specifying ranges.

3. Quota exceeded on bulk operations -- The Sheets API has per-minute read and write quotas. Add delays between batch operations or request a quota increase in the GCP console. The default quota is 60 read requests and 60 write requests per minute per user.