# Google Sheets on boxd

> Google Sheets is a cloud-based spreadsheet tool enabling real-time collaboration, data analysis, and integration with other Google Workspace apps.

- Page: https://boxd.sh/integrations/googlesheets/
- CLI: `run googlesheets` (53 commands, 34 marked common)
- SDK: `import { googlesheets } from "@boxd/run"`; every parameter and response type is at `@boxd/run/googlesheets`
- Triggers: 16
- Connect: `run auth googlesheets` (Sign in with Google Sheets), or https://app.boxd.sh/integrations/detail/googlesheets
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth googlesheets      # once: prints a link to connect your account
run googlesheets           # list its commands
run googlesheets search-spreadsheets
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { googlesheets } from "@boxd/run";

const result = await googlesheets.searchSpreadsheets({});
console.log(result);

googlesheets.on("new-spreadsheet-created", async (event) => {
  // New Spreadsheet Created: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run googlesheets.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run googlesheets <command> --help` lists the optional ones. "common" marks what `run googlesheets` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-sheet` ·common | `googlesheets.addSheet()` | `--spreadsheet-id` | 5 | Adds a new sheet to a spreadsheet |
| `aggregate-column-data` | `googlesheets.aggregateColumnData()` | `--operation` `--sheet-name` `--spreadsheet-id` `--target-column` | 6 | Searches for rows where a specific column matches a value and performs mathematical operations on data from another column |
| `append-dimension` ·common | `googlesheets.appendDimension()` | `--dimension` `--length` `--sheet-id` `--spreadsheet-id` | 3 | Append new rows or columns to a sheet, increasing its size |
| `auto-resize-dimensions` | `googlesheets.autoResizeDimensions()` | `--dimension` `--end-index` `--spreadsheet-id` `--start-index` | 2 | Auto-fit column widths or row heights for a dimension range using batchUpdate.autoResizeDimensions |
| `batch-clear-values-by-data-filter` ·common | `googlesheets.batchClearValuesByDataFilter()` | `--dataFilters` `--spreadsheetId` | 0 | Clears one or more ranges of values from a spreadsheet using data filters |
| `batch-get` ·common | `googlesheets.batchGet()` | `--spreadsheet-id` | 5 | Retrieves data from specified cell ranges in a Google Spreadsheet |
| `batch-update` ·common ·deprecated | `googlesheets.batchUpdate()` | `--sheet-name` `--spreadsheet-id` `--values` | 3 | Use values-update instead |
| `batch-update-values-by-data-filter` | `googlesheets.batchUpdateValuesByDataFilter()` | `--data` `--spreadsheetId` `--valueInputOption` | 3 | Update values in ranges matching data filters |
| `clear-basic-filter` ·common | `googlesheets.clearBasicFilter()` | `--sheet-id` `--spreadsheet-id` | 3 | Clear the basic filter from a sheet |
| `clear-values` | `googlesheets.clearValues()` | `--range` `--spreadsheet-id` | 0 | Clears cell content (preserving formatting and notes) from a specified A1 notation range in a Google Spreadsheet; the range must correspond to an existing sheet and cells |
| `create-chart` | `googlesheets.createChart()` | `--chart-type` `--data-range` `--sheet-id` `--spreadsheet-id` | 9 | Create a chart in a Google Sheets spreadsheet using the specified data range and chart type |
| `create-google-sheet1` ·common | `googlesheets.createGoogleSheet1()` | — | 3 | Creates a new Google Spreadsheet in Google Drive |
| `create-spreadsheet-column` | `googlesheets.createSpreadsheetColumn()` | `--spreadsheet-id` | 7 | Creates a new column in a Google Spreadsheet |
| `create-spreadsheet-row` | `googlesheets.createSpreadsheetRow()` | `--spreadsheet-id` | 7 | Inserts a new, empty row into a specified sheet of a Google Spreadsheet at a given index, optionally inheriting formatting from the row above |
| `delete-chart` | `googlesheets.deleteChart()` | `--chart-id` `--spreadsheet-id` | 0 | Delete an existing chart from a Google Sheets spreadsheet |
| `delete-dimension` ·common | `googlesheets.deleteDimension()` | `--spreadsheet-id` | 9 | Delete specified rows or columns from a sheet in a Google Spreadsheet |
| `delete-sheet` ·common | `googlesheets.deleteSheet()` | `--sheetId` `--spreadsheetId` | 3 | Delete a sheet (worksheet) from a spreadsheet |
| `execute-sql` ·deprecated | `googlesheets.executeSql()` | `--spreadsheet-id` `--sql` | 2 | Use direct Google Sheets actions instead: - values-get / batch-get for reads - values-update / update-values-batch / spreadsheets-values-append for writes Execute SQL queries against Google Sheets… |
| `find-replace` ·common | `googlesheets.findReplace()` | `--find` `--replace` `--spreadsheetId` | 13 | Find and replace text in a Google Spreadsheet |
| `find-worksheet-by-title` ·deprecated | `googlesheets.findWorksheetByTitle()` | `--spreadsheet-id` `--worksheet-title` | 0 | Use GetSpreadsheetInfo instead |
| `format-cell` | `googlesheets.formatCell()` | `--spreadsheet-id` | 35 | Applies text and background cell formatting to a specified range in a Google Sheets worksheet |
| `get-batch-values` ·common ·deprecated | `googlesheets.getBatchValues()` | `--ranges` `--spreadsheet-id` | 3 | Use batch-get instead |
| `get-conditional-format-rules` | `googlesheets.getConditionalFormatRules()` | `--spreadsheet-id` | 3 | List conditional formatting rules for each sheet (or a selected sheet) in a normalized, easy-to-edit form |
| `get-data-validation-rules` | `googlesheets.getDataValidationRules()` | `--spreadsheetId` | 4 | Extract data validation rules from a Google Sheets spreadsheet |
| `get-sheet-names` ·common | `googlesheets.getSheetNames()` | `--spreadsheet-id` | 1 | Lists all worksheet names from a specified Google Spreadsheet (which must exist), useful for discovering sheets before further operations |
| `get-spreadsheet-by-data-filter` ·common | `googlesheets.getSpreadsheetByDataFilter()` | `--spreadsheetId` | 3 | Returns the spreadsheet at the given ID, filtered by the specified data filters |
| `get-spreadsheet-info` ·common | `googlesheets.getSpreadsheetInfo()` | — | 5 | Retrieves metadata for a Google Spreadsheet using its ID |
| `get-table-schema` ·deprecated | `googlesheets.getTableSchema()` | `--spreadsheet-id` `--table-name` | 2 | Use get-sheet-names and get-spreadsheet-info for sheet structure metadata, and values-get for direct range inspection |
| `insert-dimension` ·common | `googlesheets.insertDimension()` | `--insert-dimension` `--spreadsheet-id` | 3 | Insert new rows or columns into a sheet at a specified location |
| `list-charts` ·common | `googlesheets.listCharts()` | `--spreadsheet-id` | 3 | Lists all charts in a Google Sheets spreadsheet across all sheets, returning chart_id, sheet metadata, chart type, title, and position |
| `list-tables` ·deprecated | `googlesheets.listTables()` | `--spreadsheet-id` | 3 | Use get-sheet-names for tab discovery and get-spreadsheet-info for full sheet metadata |
| `lookup-spreadsheet-row` | `googlesheets.lookupSpreadsheetRow()` | `--query` `--spreadsheet-id` | 5 | Finds the first row in a Google Spreadsheet where a cell's entire content exactly matches the query string, searching within a specified A1 notation range or the first sheet by default |
| `move-chart` ·common | `googlesheets.moveChart()` | `--chart-id` `--spreadsheet-id` | 9 | Move or resize an existing chart on a Google Sheets spreadsheet |
| `mutate-conditional-format-rules` ·common | `googlesheets.mutateConditionalFormatRules()` | `--operation` `--sheet-id` `--spreadsheet-id` | 3 | Add, update, delete, or reorder conditional format rules on a Google Sheet |
| `query-table` ·deprecated | `googlesheets.queryTable()` | `--spreadsheet-id` `--sql` | 1 | Use values-get / batch-get for table reads and lookup-spreadsheet-row for row lookup/filter workflows |
| `search-developer-metadata` ·common | `googlesheets.searchDeveloperMetadata()` | `--dataFilters` `--spreadsheetId` | 0 | Search for developer metadata in a spreadsheet |
| `search-spreadsheets` ·common | `googlesheets.searchSpreadsheets()` | — | 11 | Search for Google Spreadsheets using various filters including name, content, date ranges, and more |
| `set-basic-filter` ·common | `googlesheets.setBasicFilter()` | `--filter` `--spreadsheetId` | 3 | Set a basic filter on a sheet in a Google Spreadsheet |
| `set-data-validation-rule` ·common | `googlesheets.setDataValidationRule()` | `--end-column-index` `--end-row-index` `--mode` `--sheet-id` `--spreadsheet-id` `--start-column-index` `--start-row-index` | 9 | Set or clear data validation rules (including dropdowns) on a range in Google Sheets |
| `sheet-from-json` ·deprecated | `googlesheets.sheetFromJson()` | `--sheet-json` `--sheet-name` `--title` | 0 | Use create-google-sheet1 + update-values-batch (or values-update / spreadsheets-values-append) instead |
| `sort-range` ·common | `googlesheets.sortRange()` | `--range` `--sortSpecs` `--spreadsheet-id` | 3 | Sorts data within a specified range in a Google Sheet based on one or more sort criteria |
| `spreadsheets-sheets-copy-to` ·common | `googlesheets.spreadsheetsSheetsCopyTo()` | `--destination-spreadsheet-id` `--sheet-id` `--spreadsheet-id` | 0 | Copy a single sheet from a spreadsheet to another spreadsheet |
| `spreadsheets-values-append` ·common | `googlesheets.spreadsheetsValuesAppend()` | `--range` `--spreadsheetId` `--valueInputOption` `--values` | 5 | Append values to a spreadsheet |
| `spreadsheets-values-batch-clear` ·common | `googlesheets.spreadsheetsValuesBatchClear()` | `--ranges` `--spreadsheet-id` | 0 | Clear one or more ranges of values from a spreadsheet |
| `spreadsheets-values-batch-get-by-data-filter` ·common | `googlesheets.spreadsheetsValuesBatchGetByDataFilter()` | `--dataFilters` `--spreadsheetId` | 3 | Return one or more ranges of values from a spreadsheet that match the specified data filters |
| `update-chart` | `googlesheets.updateChart()` | `--chart-id` `--chart-spec` `--spreadsheet-id` | 0 | Update the specification of an existing chart in a Google Sheets spreadsheet |
| `update-dimension-properties` ·common | `googlesheets.updateDimensionProperties()` | `--dimension` `--end-index` `--spreadsheet-id` `--start-index` | 7 | Hide/unhide rows or columns and set row heights or column widths |
| `update-sheet-properties` ·common | `googlesheets.updateSheetProperties()` | `--spreadsheetId` `--updateSheetProperties` | 3 | Update properties of a sheet (worksheet) within a Google Spreadsheet, such as its title, index, visibility, tab color, or grid properties |
| `update-spreadsheet-properties` ·common | `googlesheets.updateSpreadsheetProperties()` | `--fields` `--properties` `--spreadsheetId` | 3 | Update SPREADSHEET-LEVEL properties such as the spreadsheet's title, locale, time zone, or auto-recalculation settings |
| `update-values-batch` ·common | `googlesheets.updateValuesBatch()` | `--data` `--spreadsheet-id` `--valueInputOption` | 3 | Set values in one or more ranges of a spreadsheet |
| `upsert-rows` ·common | `googlesheets.upsertRows()` | `--rows` `--sheetName` `--spreadsheetId` | 6 | Upsert rows - update existing rows by key, append new ones |
| `values-get` ·common | `googlesheets.valuesGet()` | `--range` `--spreadsheet-id` | 5 | Returns a range of values from a spreadsheet |
| `values-update` ·common | `googlesheets.valuesUpdate()` | `--range` `--spreadsheet-id` `--value-input-option` `--values` | 5 | Set values in a range of a Google Spreadsheet |

## Triggers

`googlesheets.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"aggregate-metric-changed"` | Aggregate Metric Changed | `spreadsheet_id` `sheet_name` `target_column` `operation` | Triggers when an aggregate metric (SUM/COUNT/AVG/MIN/MAX) changes in a Google Sheets spreadsheet |
| `"cell-range-values-changed"` | Cell Range Values Changed | `spreadsheet_id` `range` | Triggers when values in a specified A1 range change in Google Sheets |
| `"conditional-format-rule-changed"` | Conditional Format Rule Changed | `spreadsheet_id` | Triggers when conditional formatting rules change in a Google Spreadsheet |
| `"data-validation-rule-changed"` | Data Validation Rule Changed | `spreadsheet_id` | Triggers when data validation rules change (added/updated/removed) in a Google Spreadsheet |
| `"developer-metadata-changed"` | Developer Metadata Changed | `spreadsheet_id` | Triggers when developer metadata entries change (new/updated/removed) in a Google Spreadsheet |
| `"filtered-range-values-changed"` | Filtered Range Values Changed | `spreadsheet_id` `data_filters` | Polling trigger that monitors Google Sheets filtered ranges for value changes |
| `"new-rows"` | New Rows in Google Sheet | `spreadsheet_id` | Simple polling trigger that monitors Google Sheets for new rows |
| `"new-sheet-added"` | New Sheet Added in Google Spreadsheet | `spreadsheet_id` | Polling trigger that detects when a new sheet is added to a Google Spreadsheet |
| `"new-spreadsheet-created"` | New Spreadsheet Created | — | Triggers when a new Google Spreadsheet is created |
| `"spreadsheet-metadata-changed"` | Spreadsheet Metadata Changed | `spreadsheet_id` | Polling trigger that detects when a Google Spreadsheet's metadata changes |
| `"spreadsheet-properties-changed"` | Spreadsheet Properties Changed | `spreadsheet_id` | Polling trigger that detects when a Google Spreadsheet's top-level properties change |
| `"spreadsheet-row-changed"` | Spreadsheet Row Changed | `spreadsheet_id` `query` | Triggers when a looked-up spreadsheet row changes |
| `"spreadsheet-search-match"` | Spreadsheet Search Match | — | Triggers when a new spreadsheet appears that matches a saved search |
| `"table-query-result-changed"` | Table Query Result Changed | `spreadsheet_id` `sql` | Triggers when the result set of a saved table query changes in Google Sheets |
| `"table-schema-changed"` | Table Schema Changed | `spreadsheet_id` `table_name` | Polling trigger that detects when a table's schema changes in Google Sheets |
| `"worksheet-names-changed"` | Worksheet Names Changed | `spreadsheet_id` | Triggers when the set of worksheet/tab names changes in a Google Spreadsheet |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.