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