Skip to main content

​
Overview

The Google Sheets API allows you to read, write, and format spreadsheet data programmatically. API Name: sheets
Version: v4
Official Documentation: Sheets API Reference

​
Common Resources

​
Spreadsheets

Create and manage spreadsheets.
​
spreadsheetId
string
required
The spreadsheet ID (found in the URL)
​
range
string
A1 notation range (e.g., "Sheet1!A1:D10")
​
includeGridData
boolean
Whether to include cell data in the response

​
Values

Read and write cell values.
​
spreadsheetId
string
required
The spreadsheet ID
​
range
string
required
A1 notation range
​
valueInputOption
string
How to interpret input: RAW or USER_ENTERED

​
Common Methods

​
Create Spreadsheet

gws sheets spreadsheets create --json '{
  "properties": {
    "title": "Q1 Budget 2026"
  }
}'
​
spreadsheetId
string
The ID of the created spreadsheet
​
spreadsheetUrl
string
The URL to open the spreadsheet in the browser

​
Get Spreadsheet

gws sheets spreadsheets get --params '{
  "spreadsheetId": "1a2b3c4d5e6f7g8h9i"
}'

​
Read Values

gws sheets spreadsheets values get --params '{
  "spreadsheetId": "1a2b3c4d5e6f7g8h9i",
  "range": "Sheet1!A1:D10"
}'
​
range
string
The range that was read
​
values
array
2D array of cell values

​
Write Values

gws sheets spreadsheets values update \
  --params '{
    "spreadsheetId": "1a2b3c4d5e6f7g8h9i",
    "range": "Sheet1!A1",
    "valueInputOption": "USER_ENTERED"
  }' \
  --json '{
    "values": [
      ["Name", "Email", "Status"],
      ["Alice", "alice@example.com", "Active"],
      ["Bob", "bob@example.com", "Pending"]
    ]
  }'

​
Append Values

gws sheets spreadsheets values append \
  --params '{
    "spreadsheetId": "1a2b3c4d5e6f7g8h9i",
    "range": "Sheet1!A1",
    "valueInputOption": "USER_ENTERED"
  }' \
  --json '{
    "values": [["New Row", "data1", "data2"]]
  }'

​
Batch Update

gws sheets spreadsheets batchUpdate \
  --params '{"spreadsheetId": "1a2b3c4d5e6f7g8h9i"}' \
  --json '{
    "requests": [
      {
        "addSheet": {
          "properties": {"title": "New Sheet"}
        }
      },
      {
        "updateSheetProperties": {
          "properties": {
            "sheetId": 0,
            "title": "Renamed Sheet"
          },
          "fields": "title"
        }
      }
    ]
  }'

​
Value Examples

gws sheets spreadsheets values get --params '{
  "spreadsheetId": "1a2b3c4d5e6f7g8h9i",
  "range": "Sheet1!A1"
}'

​
Response Format

Read values response: 
{
  "range": "Sheet1!A1:D3",
  "majorDimension": "ROWS",
  "values": [
    ["Name", "Email", "Department", "Status"],
    ["Alice", "alice@example.com", "Engineering", "Active"],
    ["Bob", "bob@example.com", "Sales", "Active"]
  ]
}
Create spreadsheet response: 
{
  "spreadsheetId": "1a2b3c4d5e6f7g8h9i",
  "spreadsheetUrl": "https://docs.google.com/spreadsheets/d/1a2b3c4d5e6f7g8h9i/edit",
  "properties": {
    "title": "Q1 Budget 2026",
    "locale": "en_US",
    "timeZone": "America/Los_Angeles"
  }
}
  • +append - Append a row to a spreadsheet
  • +read - Read values from a spreadsheet

​
Key Resources

  • spreadsheets - Create and manage spreadsheets
  • spreadsheets.values - Read and write cell values
  • spreadsheets.sheets - Manage individual sheets
  • spreadsheets.developerMetadata - Store custom metadata

​
Common Operations

​
Formatting

Use batchUpdate to format cells: 
gws sheets spreadsheets batchUpdate \
  --params '{"spreadsheetId": "1a2b3c4d5e6f7g8h9i"}' \
  --json '{
    "requests": [{
      "repeatCell": {
        "range": {"sheetId": 0, "startRowIndex": 0, "endRowIndex": 1},
        "cell": {
          "userEnteredFormat": {
            "textFormat": {"bold": true}
          }
        },
        "fields": "userEnteredFormat.textFormat.bold"
      }
    }]
  }'

​
Learn More

​
Schema Inspection

Before calling any method, inspect its schema: 
gws schema sheets.spreadsheets.create
gws schema sheets.spreadsheets.values.update