gws-sheets-write

name	gws-sheets-write
description	Google Sheets: Write values to a specific range.
metadata	{"version":"0.22.0","openclaw":{"category":"productivity","requires":{"bins":["gws"]},"cliHelp":"gws schema sheets.spreadsheets.values.update"},"maxent":{"requires":{"bins":[{"name":"gws","install":{"windows":{"method":"winget","id":"nekr0z.gws"},"linux":{"method":"script","url":"https://github.com/nicholasgasior/gws/releases/latest/download/install.sh"},"darwin":{"method":"brew","id":"gws"}}}]}}}

sheets +write

PREREQUISITE: Read ../gws-shared/SKILL.md for auth, global flags, and security rules. If missing, run gws generate-skills to create it.

Write values (or formulas) to a specific cell or range. Unlike +append which always adds to the next empty row, +write targets an exact location and overwrites it.

Command

gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"ID","range":"RANGE","valueInputOption":"USER_ENTERED"}' \
  --json '{"values": ROWS}'

[!IMPORTANT] Always wrap --params and --json in single quotes. Never use double quotes with backslash-escaping (\"). Single quotes require no escaping and work reliably across shells.

Parameters

Parameter	In --params	Required	Description
spreadsheetId	✓	✓	Spreadsheet ID
range	✓	✓	Target range in A1 notation (e.g. D1, A1:C3, Sheet2!B2:B10)
valueInputOption	✓	—	USER_ENTERED (default — evaluates formulas) or RAW (stores text literally)

Values Format (--json)

values is an array of rows. Each row is an array of cell values.

Shape	JSON
Single cell	[[value]]
Single column (N rows)	[[v1],[v2],[v3]]
Single row (N columns)	[[v1,v2,v3]]
2D block	[[r1c1,r1c2],[r2c1,r2c2]]

Examples

# Write a single header cell
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"ID","range":"D1","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[["multipopul"]]}'

# Write a column of values (D2:D6)
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"ID","range":"D2:D6","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[[112200000],[6483000],[27007464],[64620000],[25007691]]}'

# Write a column of formulas (evaluates =B2*3 etc.)
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"ID","range":"D2:D6","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[["=B2*3"],["=B3*3"],["=B4*3"],["=B5*3"],["=B6*3"]]}'

# Write header + data in one call
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"ID","range":"A1:C3","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[["City","Population","Country"],["Tokyo",37400000,"Japan"],["Paris",2161000,"France"]]}'

# Write to a specific sheet tab (use SheetName!Range)
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"ID","range":"Sheet2!A1","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[["hello"]]}'

Tips

• Formulas: Use USER_ENTERED so that =B2*3 is evaluated, not stored as text.
• Sheet names with spaces: Write My Sheet!A1 — do not wrap in single quotes inside the JSON string (e.g. 'My Sheet'!A1 will fail with a parse error).
• Overwrite behaviour: This command replaces whatever is in the target range. It does not shift existing rows.
• Header + data together: Cover the full range including row 1 and put the header as the first inner array.
• Confirm range size: The range in --params and the shape of values should match. If they differ, the API writes as many cells as the values array contains within the range bounds.

[!CAUTION] This is a write command — confirm with the user before executing.

See Also

• gws-shared — Global flags and auth
• gws-sheets — All read and write spreadsheets commands
• gws-sheets-append — Append rows without targeting a range