Google Sheets (Cloud Spreadsheet Skill)

Access the Google Sheets API (v4) with managed OAuth authentication via Maton. Create spreadsheets, read cell values, update data, append rows, and manage formulas/formatting.

⚠️ Cloud vs. Local File Scope Distinction:

• google-sheets (This Skill): Exclusively for online Google Sheets cloud spreadsheets (docs.google.com/spreadsheets/d/{spreadsheetId}). Interacts directly with Google's cloud servers via Maton OAuth API proxy.
• xlsx Skill: For reading, creating, or editing local .xlsx / .xls / .csv files stored on the local disk.

Quick Start

CLI:

# Read values from a sheet range
maton google-sheets values get <spreadsheetId> --range 'Sheet1!A1:D10'

# Create a new spreadsheet
maton google-sheets spreadsheet create --title 'Q3 Financial Report' --sheet-title 'Summary'

# Update values in a sheet range
maton google-sheets values update <spreadsheetId> --range 'Sheet1!A1:B2' --json-values '[["Item", "Price"], ["Widget", 19.99]]'

# Append a row of data
maton google-sheets values append <spreadsheetId> --range 'Sheet1!A1' --values '2026-07-23,Subscription Revenue,1250.00'

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-sheets/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1:Z100')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://api.maton.ai/google-sheets/{native-api-path}

Maton proxies requests to sheets.googleapis.com and automatically injects your OAuth token.

CLI Installation (optional — agent decides)

Maton CLI is optional. Agent can decide whether to install it based on the environment.

macOS / Linux

curl -fsSL https://maton.ai/install.sh | bash

Windows

irm https://maton.ai/install.ps1 | iex

npm (cross-platform)

npm install -g @maton/cli

Homebrew (macOS)

brew install maton-ai/cli/maton

After installation, verify with:

maton --version

Authentication

CLI:

maton login                          # Opens browser for API key
maton login --interactive            # Skip browser, paste API key directly
maton whoami                         # Show current auth state

Manual:

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key
4. Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Connection Management

Manage your Google Sheets OAuth connections at https://api.maton.ai.

List Connections

CLI:

maton connection list google-sheets --status ACTIVE

maton api -X GET /connections -f app=google-sheets -f status=ACTIVE

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=google-sheets&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

CLI:

maton connection create google-sheets

maton api /connections -f app=google-sheets

Response:

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-sheets"
  }
}

Open the returned url in a browser to complete OAuth authorization.

Get Connection

CLI:

maton connection get {connection_id}                 # alias: maton connection view

maton api /connections/{connection_id}

Delete Connection

CLI:

maton connection delete {connection_id} --yes

maton api -X DELETE /connections/{connection_id}

Specifying Connection

If you have multiple Google Sheets connections, specify which one to use:

CLI:

maton google-sheets values get <spreadsheetId> --range 'Sheet1!A1:D10' --connection {connection_id}

maton api /google-sheets/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1:D10 --connection {connection_id}

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-sheets/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1:D10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always specify the connection to ensure requests go to the intended account.

Security & Permissions

• Access is scoped to Google Sheets within the connected Google account.
• All write, update, append, and delete operations require explicit user approval. Confirm target spreadsheet ID, sheet name, and cell values with the user before executing.

API Reference

1. Get Spreadsheet Metadata

Retrieve spreadsheet properties, sheets list, grid dimensions, and formulas.

GET /google-sheets/v4/spreadsheets/{spreadsheetId}

Example CLI:

maton google-sheets spreadsheet get <spreadsheetId>
maton google-sheets spreadsheet get <spreadsheetId> --include-grid-data --json

2. Read Cell Values

Read cell values from a specified range (e.g., Sheet1!A1:C5 or A:D).

GET /google-sheets/v4/spreadsheets/{spreadsheetId}/values/{range}

Query Parameters:

• valueRenderOption - FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA
• dateTimeRenderOption - SERIAL_NUMBER or FORMATTED_STRING

Example CLI:

maton google-sheets values get <spreadsheetId> --range 'Sheet1!A1:E50'
maton google-sheets values get <spreadsheetId> --range 'Sheet1!A1:B10' --value-render-option UNFORMATTED_VALUE --json

3. Update Cell Range

Write or replace cell values in a range.

Example CLI:

# Comma-separated row
maton google-sheets values update <spreadsheetId> --range 'Sheet1!A1' --values 'Alice,100,true'

# Multi-row via JSON values
maton google-sheets values update <spreadsheetId> --range 'Sheet1!A1:B2' --json-values '[["Item","Price"],["Widget",19.99]]'

Raw REST API:

PUT /google-sheets/v4/spreadsheets/{spreadsheetId}/values/{range}?valueInputOption=USER_ENTERED
Content-Type: application/json

{
  "range": "Sheet1!A1:B2",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Price"],
    ["Widget", 19.99]
  ]
}

• valueInputOption: USER_ENTERED (parses numbers, dates, formulas like =SUM(...)) or RAW (stores raw strings).

4. Append Rows to Sheet

Append new rows after the last row of data in a table range.

Example CLI:

# Comma-separated row
maton google-sheets values append <spreadsheetId> --range 'Sheet1!A1' --values '2026-07-23,Subscription Revenue,1250.00'

# Multi-row via JSON values
maton google-sheets values append <spreadsheetId> --range 'Sheet1!A1' --json-values '[["2026-07-24","Consulting",800.00]]' --insert-data-option INSERT_ROWS

5. Clear Cell Values

Clear values from a range without deleting the cells or formatting.

Example CLI:

maton google-sheets values clear <spreadsheetId> --range 'Sheet1!A1:D10'

6. Create New Spreadsheet

Create a blank spreadsheet with initial title and optional first sheet title.

Example CLI:

maton google-sheets spreadsheet create --title 'Q3 Financial Report' --sheet-title 'Summary'

7. Copy Sheet Between Spreadsheets

Copy a sheet from a source spreadsheet to a destination spreadsheet.

Example CLI:

maton google-sheets sheet copy <sourceSpreadsheetId> --sheet-id 0 --to <destSpreadsheetId>

8. Batch Update Sheet Formatting & Layout

Add sheets, delete sheets, change colors, format borders, update column widths, or set grid cell properties.

POST /google-sheets/v4/spreadsheets/{spreadsheetId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Analytics Data"
        }
      }
    }
  ]
}

Example CLI:

maton api -X POST /google-sheets/v4/spreadsheets/<spreadsheetId>:batchUpdate \
  -d '{"requests":[{"addSheet":{"properties":{"title":"Analytics Data"}}}]}'

Code Examples

CLI

# Create spreadsheet
maton google-sheets spreadsheet create --title 'Company Budget' --sheet-title '2026'

# Read values
maton google-sheets values get <spreadsheetId> --range '2026!A1:C10'

# Append a record
maton google-sheets values append <spreadsheetId> --range '2026!A1' --values 'Cloud Hosting,350.00,Approved'

JavaScript

// Read values from spreadsheet
const response = await fetch(
  'https://api.maton.ai/google-sheets/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1:D10?valueRenderOption=FORMATTED_VALUE',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const result = await response.json();
console.log(result.values);

// Append rows
const appendResponse = await fetch(
  'https://api.maton.ai/google-sheets/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1:append?valueInputOption=USER_ENTERED',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      values: [
        ['Alice', 'Engineering', '120000']
      ]
    })
  }
);
console.log('Appended updates:', await appendResponse.json());

Python: Read Values & Convert to Dict

import os, json, urllib.request

spreadsheet_id = "<spreadsheetId>"
cell_range = "Sheet1!A1:C10"

url = f"https://api.maton.ai/google-sheets/v4/spreadsheets/{spreadsheet_id}/values/{cell_range}"
req = urllib.request.Request(url)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')

res = json.load(urllib.request.urlopen(req))
rows = res.get('values', [])

if rows:
    headers = rows[0]
    data = [dict(zip(headers, row)) for row in rows[1:]]
    print(json.dumps(data, indent=2))

Notes

• Spreadsheet IDs are opaque strings (extracted from https://docs.google.com/spreadsheets/d/<spreadsheetId>/edit).
• A1 notation ranges containing spaces or special characters in sheet names should be quoted (e.g. 'Q3 Report'!A1:D10).
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (such as [, ]) to disable glob parsing.
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.

Error Handling

Troubleshooting: API Key Issues

CLI:

maton whoami
maton connection list google-sheets

Manual:

echo $MATON_API_KEY
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with google-sheets. For example:

• Correct: https://api.maton.ai/google-sheets/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1:D10
• Incorrect: https://api.maton.ai/sheets/v4/spreadsheets/<spreadsheetId>/values/Sheet1!A1:D10

Resources

• Google Sheets REST API v4 Reference
• Values API Guide
• Maton CLI Google Sheets Manual
• Maton Community
• Maton Support