Google Sheets

Read, create, and edit Google Sheets using the Sheets API v4 with a user refresh token.

IMPORTANT: User approval required for all writes. Before any create, update, append, or batch update action, show the planned content first and wait for explicit take off approval. Do not mutate anything before that approval.

Configuration

The shared Google credential configuration is defined once in the google-oauth skill: skills/google-oauth/SKILL.md.

API Reference

All Google API requests use:

-H "Authorization: Bearer $ACCESS_TOKEN"
-H "Content-Type: application/json"

Read the configured values before making any calls.

Refresh an Access Token

Mint the access token from the stored refresh token with the recipe in the google-oauth skill: skills/google-oauth/SKILL.md.

If the refresh token is invalid or revoked, re-run the bootstrap flow in the google-oauth skill: skills/google-oauth/SKILL.md.

Create a Spreadsheet

curl -s -X POST https://sheets.googleapis.com/v4/spreadsheets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"title":"Spreadsheet Title"}}'

After a successful create, return the editor URL:

https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit

Read Spreadsheet Metadata

curl -s "https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Returns spreadsheet properties, sheet names, grid dimensions, and other metadata. To list only sheet titles, inspect sheets[].properties.title in the response.

Read Values

curl -s "https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/RANGE" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

RANGE uses A1 notation, e.g. Sheet1!A1:D10 or Sheet1!A:A. The response contains a values array of rows.

Write Values

curl -s -X PUT "https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/RANGE?valueInputOption=USER_ENTERED" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "range": "RANGE",
    "majorDimension": "ROWS",
    "values": [
      ["A1 value", "B1 value"],
      ["A2 value", "B2 value"]
    ]
  }'

valueInputOption=USER_ENTERED parses values as if typed into the UI (numbers, dates, formulas are interpreted). Use RAW to store literal strings.

Append Values

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/RANGE:append?valueInputOption=USER_ENTERED" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "range": "RANGE",
    "majorDimension": "ROWS",
    "values": [
      ["A value", "B value"]
    ]
  }'

Appends rows after the last row with data in the specified range. The RANGE determines which table to append to (e.g. Sheet1!A:B).

Batch Update

Use spreadsheets.batchUpdate for structural changes (add/delete sheets, formatting, merge cells, resize, conditional formatting, etc.):

curl -s -X POST "https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "addSheet": {
          "properties": { "title": "New Sheet" }
        }
      }
    ]
  }'

Common request types: addSheet, deleteSheet, updateSheetProperties, mergeCells, repeatCell (for formatting), autoResizeDimensions, addConditionalFormatRule.

Bootstrap / Re-Authorization

All Google integrations share one OAuth client and refresh token (the google section of ~/.charliebot/credentials.yaml). One-time setup and re-authorization after expiry follow the google-oauth skill: skills/google-oauth/SKILL.md.

Workflow

1. Read the token and client values from ~/.charliebot/credentials.yaml (section google).
2. Refresh an access token with the OAuth token endpoint.
3. For reads, call spreadsheets.get for metadata or spreadsheets.values.get for cell data.
4. For writes, show the exact planned content first and wait for explicit take off approval.
5. After approval, create, write, append, or batch update via Sheets API. After a successful create, return https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit.