gws-sheets

name	gws-sheets
description	Google Sheets 读写数据。不用于：本地 Excel/CSV（用 xlsx 技能）

Requires: gws CLI installed and authenticated (gws auth login).

Command syntax

gws sheets <resource> <method> --params '{"key":"val"}' --json '{"key":"val"}'

Read cell range

{"command": "gws sheets spreadsheets.values get --params '{\"spreadsheetId\":\"SPREADSHEET_ID\",\"range\":\"Sheet1!A1:D10\"}'", "timeout": 30000}

Read entire sheet

{"command": "gws sheets spreadsheets.values get --params '{\"spreadsheetId\":\"SPREADSHEET_ID\",\"range\":\"Sheet1\"}'", "timeout": 30000}

Write cells (overwrite)

{"command": "gws sheets spreadsheets.values update --params '{\"spreadsheetId\":\"SPREADSHEET_ID\",\"range\":\"Sheet1!A1\",\"valueInputOption\":\"USER_ENTERED\"}' --json '{\"values\":[[\"Name\",\"Score\"],[\"Alice\",95],[\"Bob\",87]]}'", "timeout": 30000}

Append rows

{"command": "gws sheets spreadsheets.values append --params '{\"spreadsheetId\":\"SPREADSHEET_ID\",\"range\":\"Sheet1!A:A\",\"valueInputOption\":\"USER_ENTERED\"}' --json '{\"values\":[[\"Charlie\",92]]}'", "timeout": 30000}

Get spreadsheet metadata

{"command": "gws sheets spreadsheets get --params '{\"spreadsheetId\":\"SPREADSHEET_ID\",\"fields\":\"sheets.properties\"}'", "timeout": 30000}

Clear range

{"command": "gws sheets spreadsheets.values clear --params '{\"spreadsheetId\":\"SPREADSHEET_ID\",\"range\":\"Sheet1!A1:D10\"}'", "timeout": 30000}

Batch read multiple ranges

{"command": "gws sheets spreadsheets.values batchGet --params '{\"spreadsheetId\":\"SPREADSHEET_ID\",\"ranges\":\"Sheet1!A1:B5\",\"ranges\":\"Sheet2!A1:C3\"}'", "timeout": 30000}

Rules

• spreadsheetId is in the URL: https://docs.google.com/spreadsheets/d/{SPREADSHEET_ID}/edit.
• valueInputOption: USER_ENTERED (parses formulas/dates) or RAW (literal text).
• Range notation: Sheet1!A1:D10, Sheet1!A:A (whole column), Sheet1 (whole sheet).
• Always use fields parameter on spreadsheets.get to limit metadata size.
• Use gws schema sheets.spreadsheets.values.update to discover all parameters.