google-sheets

name	google-sheets
description	Create spreadsheets, read data, and manage Google Sheets. Use when asked to create sheets, add data to spreadsheets, lookup rows, update cells, or manage sheet data.

Google Sheets

Create spreadsheets, read data, add rows, and manage Google Sheets. Connect your Google account to work with spreadsheet data, perform lookups, and automate sheet operations.

Requirements

• Install the orth CLI
• Connect your Google Sheets at https://orthogonal.com/dashboard/integrations
• OAuth connection must be active (HTTP 428 response means not connected)

Actions

Create Spreadsheet

Create a new Google Sheets spreadsheet.

orth run google-sheets /create-spreadsheet --body '{
  "title": "Project Tracker"
}'

Parameters:

• title (required) - Title for the new spreadsheet

Get Sheet Names

Retrieve all sheet names and IDs from a spreadsheet.

orth run google-sheets /get-sheet-names --body '{
  "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
}'

Parameters:

• spreadsheet_id (required) - Google Sheets spreadsheet ID

Add Row

Add a new row to a specific sheet.

orth run google-sheets /add-row --body '{
  "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "sheet_id": 0,
  "insert_index": 2
}'

Parameters:

• spreadsheet_id (required) - Google Sheets spreadsheet ID
• sheet_id (required) - Sheet ID (numeric gid, not sheet name)
• insert_index - Row index to insert at (0-based)
• inherit_from_before - Inherit formatting from row above (true/false)

Lookup Row

Search for rows matching a query in the spreadsheet.

orth run google-sheets /lookup-row --body '{
  "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "query": "John Doe",
  "range": "Sheet1!A1:Z1000"
}'

Parameters:

• spreadsheet_id (required) - Google Sheets spreadsheet ID
• query (required) - Text to search for in the sheet
• range - Range to search in (A1 notation, e.g., "Sheet1!A1:Z100")
• case_sensitive - Case-sensitive search (true/false)

Get Values

Retrieve data from specific ranges in the spreadsheet.

orth run google-sheets /get-values --body '{
  "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "ranges": ["Sheet1!A1:C10", "Sheet2!A1:B5"]
}'

Parameters:

• spreadsheet_id (required) - Google Sheets spreadsheet ID
• ranges (required) - Array of ranges in A1 notation to retrieve

Update Values

Update data in specific cells or ranges.

orth run google-sheets /update-values --body '{
  "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "sheet_name": "Sheet1",
  "values": [["Name", "Age", "Email"], ["John Doe", "30", "[e-mail]"]],
  "first_cell_location": "A1"
}'

Parameters:

• spreadsheet_id (required) - Google Sheets spreadsheet ID
• sheet_name (required) - Name of the sheet to update
• values (required) - 2D array of values to write
• first_cell_location - Starting cell location (A1 notation, defaults to A1)
• valueInputOption - How values are interpreted (USER_ENTERED, RAW)
• includeValuesInResponse - Return updated values in response (true/false)

Usage Examples

Create project tracking sheet:

orth run google-sheets /create-spreadsheet -b '{"title":"Q1 Project Dashboard"}'

Get all sheet names:

orth run google-sheets /get-sheet-names -b '{"spreadsheet_id":"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"}'

Add empty row:

orth run google-sheets /add-row -b '{"spreadsheet_id":"1ABC...","sheet_id":0,"insert_index":5}'

Search for customer:

orth run google-sheets /lookup-row -b '{"spreadsheet_id":"1ABC...","query":"[e-mail]","range":"Customers!A:Z"}'

Get header row:

orth run google-sheets /get-values -b '{"spreadsheet_id":"1ABC...","ranges":["Sheet1!1:1"]}'

Get specific columns:

orth run google-sheets /get-values -b '{"spreadsheet_id":"1ABC...","ranges":["Sheet1!A:A","Sheet1!C:C"]}'

Add new data row:

orth run google-sheets /update-values -b '{"spreadsheet_id":"1ABC...","sheet_name":"Sheet1","values":[["New Customer","John Smith","[e-mail]","2024-03-15"]],"first_cell_location":"A2"}'

Update multiple cells:

orth run google-sheets /update-values -b '{"spreadsheet_id":"1ABC...","sheet_name":"Data","values":[["Updated","Value"],["Another","Update"]],"first_cell_location":"B5","valueInputOption":"USER_ENTERED"}'

Add headers to new sheet:

orth run google-sheets /update-values -b '{"spreadsheet_id":"1ABC...","sheet_name":"Customers","values":[["Name","Email","Phone","Date Added"]],"first_cell_location":"A1"}'

A1 Notation Guide

Google Sheets uses A1 notation for cell references:

Basic ranges:

• A1 - Single cell
• A1:B2 - 2x2 range
• A:A - Entire column A
• 1:1 - Entire row 1
• A1:Z - Column A to Z in row 1

Sheet references:

• Sheet1!A1:B2 - Range in specific sheet
• 'My Sheet'!A1 - Sheet with spaces (use quotes)

Open ranges:

• A1:C - From A1 to end of column C
• A1:1 - From A1 to end of row 1

Error Handling

• HTTP 428 - Google Sheets integration not connected. Visit https://orthogonal.com/dashboard/integrations to connect your account
• 400 Bad Request - Invalid spreadsheet ID, range, or data format
• 403 Forbidden - Insufficient permissions to access or edit spreadsheet
• 404 Not Found - Spreadsheet or sheet does not exist
• 429 Rate Limited - Google Sheets API quota exceeded

Tips

• Spreadsheet IDs are found in the Google Sheets URL
• Sheet IDs are numeric (gid parameter in URL), different from sheet names
• Use sheet names (not IDs) for update-values action
• Values array must be 2D: [["row1col1", "row1col2"], ["row2col1", "row2col2"]]
• USER_ENTERED interprets formulas and formats, RAW inserts literal values
• A1 notation is case-insensitive (a1 same as A1)
• Use quotes around sheet names containing spaces
• Empty cells in values arrays are represented as empty strings
• Lookup searches all text in the specified range