# Excel on boxd

> Microsoft Excel is a powerful spreadsheet application for data analysis, calculations, and visualization, enabling users to organize and process data with formulas, charts, and pivot tables.

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

## From the shell

```sh
run auth excel      # once: prints a link to connect your account
run excel           # list its commands
run excel get-session --help
```

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 { every, excel } from "@boxd/run";

every("1 hour", async () => {
  const result = await excel.getSession({ item_id: "…" });
  console.log(result);
});
```

Run it with `run excel.run.ts`. Excel has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

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

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-chart` | `excel.addChart()` | `--item-id` `--seriesby` `--sourcedata` `--type` `--worksheet` | 2 | Add a chart to a worksheet using Microsoft Graph API |
| `add-sharepoint-worksheet` | `excel.addSharepointWorksheet()` | `--item-id` `--name` `--site-id` | 1 | Add a new worksheet to a SharePoint Excel workbook using Microsoft Graph Sites API |
| `add-table` ·common | `excel.addTable()` | `--address` `--hasHeaders` `--item-id` | 3 | Create a new table in a worksheet using the Microsoft Graph API |
| `add-table-column` | `excel.addTableColumn()` | `--index` `--item-id` `--table-id` `--values` | 2 | Add a column to a table using Microsoft Graph API |
| `add-table-row` | `excel.addTableRow()` | `--item-id` `--table-id` `--values` | 3 | Add a row to a table using Microsoft Graph API |
| `add-workbook-permission` ·common | `excel.addWorkbookPermission()` | `--item-id` `--recipients` `--roles` | 8 | Grant access to a workbook via invite |
| `add-worksheet` | `excel.addWorksheet()` | `--item-id` `--name` | 2 | Add a new worksheet to an Excel workbook using Microsoft Graph API |
| `apply-table-filter` | `excel.applyTableFilter()` | `--column-id` `--criteria` `--item-id` `--table-id` `--worksheet` | 2 | Apply a filter to a table column using Microsoft Graph API |
| `apply-table-sort` | `excel.applyTableSort()` | `--fields` `--item-id` `--table-id` `--worksheet` | 2 | Apply a sort to a table using Microsoft Graph API |
| `clear-range` | `excel.clearRange()` | `--address` `--item-id` `--worksheet-id` | 4 | Clear values, formats, or contents in a specified worksheet range |
| `clear-table-filter` | `excel.clearTableFilter()` | `--column-id` `--item-id` `--table-id` `--worksheet` | 2 | Clear a filter from a table column using Microsoft Graph API |
| `close-session` | `excel.closeSession()` | `--item-id` `--session-id` | 1 | Close an existing Excel workbook session |
| `convert-table-to-range` | `excel.convertTableToRange()` | `--item-id` `--table-id` | 2 | Convert a table to a range using Microsoft Graph API |
| `create-workbook` | `excel.createWorkbook()` | `--path` | 3 | Create a new Excel workbook file at a specified drive path |
| `delete-table-column` | `excel.deleteTableColumn()` | `--column-id` `--item-id` `--table-id` | 2 | Delete a column from a table using Microsoft Graph API |
| `delete-table-row` | `excel.deleteTableRow()` | `--item-id` `--row-index` `--table-id` | 2 | Delete a row from a table using Microsoft Graph API |
| `delete-worksheet` | `excel.deleteWorksheet()` | `--item-id` `--worksheet` | 2 | Delete a worksheet from the workbook |
| `export-workbook-to-pdf` | `excel.exportWorkbookToPdf()` | `--item-id` | 4 | Export an Excel workbook to PDF via Microsoft Graph's format conversion |
| `get-chart-axis` | `excel.getChartAxis()` | `--axis-type` `--chart-name` `--item-id` `--worksheet` | 4 | Retrieve a specific axis from a chart |
| `get-chart-data-labels` | `excel.getChartDataLabels()` | `--chart-id` `--item-id` `--worksheet-id` | 2 | Retrieve the data labels object of a chart |
| `get-chart-legend` | `excel.getChartLegend()` | `--chart-name` `--item-id` `--worksheet-id` | 4 | Retrieve the legend object of a chart |
| `get-range` | `excel.getRange()` | `--address` `--item-id` `--worksheet-id` | 2 | Get a range from a worksheet using Microsoft Graph API |
| `get-session` ·common | `excel.getSession()` | `--item-id` | 2 | Create a session for an Excel workbook using Microsoft Graph API |
| `get-sharepoint-range` | `excel.getSharepointRange()` | `--address` `--item-id` `--site-id` `--worksheet-id` | 1 | Get a range from a worksheet in SharePoint using Microsoft Graph Sites API |
| `get-sharepoint-worksheet` | `excel.getSharepointWorksheet()` | `--item-id` `--site-id` `--worksheet` | 1 | Get a worksheet by name or ID from a SharePoint Excel workbook using Microsoft Graph Sites API |
| `get-table-column` | `excel.getTableColumn()` | `--column-id` `--item-id` `--table-id` | 3 | Retrieve a specific column from a workbook table |
| `get-workbook` | `excel.getWorkbook()` | `--drive-id` `--item-id` | 2 | Retrieve the properties and relationships of a workbook |
| `get-worksheet` | `excel.getWorksheet()` | `--item-id` `--worksheet` | 2 | Get a worksheet by name or ID from an Excel workbook using Microsoft Graph API |
| `get-worksheet-used-range` | `excel.getWorksheetUsedRange()` | `--drive-id` `--item-id` `--worksheet-id` | 2 | Retrieve a worksheet's used range (active data region) without specifying a fixed range address |
| `insert-range` ·common | `excel.insertRange()` | `--address` `--item-id` `--shift` `--worksheet-id` | 2 | Insert a new cell range into a worksheet, shifting existing cells down or right |
| `list-chart-series` | `excel.listChartSeries()` | `--chart-name` `--item-id` `--worksheet` | 4 | List all data series in a chart |
| `list-charts` | `excel.listCharts()` | `--item-id` `--worksheet` | 4 | List charts in a worksheet using Microsoft Graph API |
| `list-comments` | `excel.listComments()` | `--item-id` | 4 | List comments in an Excel workbook |
| `list-drive-item-children` | `excel.listDriveItemChildren()` | `--drive-id` `--item-id` | 2 | List immediate children (files/folders) of a folder DriveItem using driveId and itemId |
| `list-files` | `excel.listFiles()` | — | 4 | List files and folders in a drive root or specified path |
| `list-named-items` | `excel.listNamedItems()` | `--item-id` | 4 | List named items in a workbook using Microsoft Graph API |
| `list-sharepoint-tables` | `excel.listSharepointTables()` | `--item-id` `--site-id` `--worksheet` | 3 | List tables in a SharePoint worksheet using Microsoft Graph Sites API |
| `list-sharepoint-worksheets` | `excel.listSharepointWorksheets()` | `--item-id` `--site-id` | 4 | List worksheets in an Excel workbook stored in SharePoint using Microsoft Graph Sites API |
| `list-table-columns` ·common | `excel.listTableColumns()` | `--item-id` `--table-id` | 4 | List columns in a table using Microsoft Graph API |
| `list-table-rows` | `excel.listTableRows()` | `--item-id` `--table-id` | 4 | List rows in a table using Microsoft Graph API |
| `list-tables` | `excel.listTables()` | `--item-id` `--worksheet` | 4 | List tables in a worksheet using Microsoft Graph API |
| `list-workbook-permissions` | `excel.listWorkbookPermissions()` | `--drive-id` `--item-id` | 5 | List permissions set on the workbook file |
| `list-worksheets` | `excel.listWorksheets()` | `--item-id` | 4 | List worksheets in an Excel workbook using Microsoft Graph API |
| `merge-cells` | `excel.mergeCells()` | `--item-id` `--range` `--worksheet` | 3 | Merge cells in a worksheet range using Microsoft Graph API |
| `protect-worksheet` | `excel.protectWorksheet()` | `--item-id` `--worksheet` | 3 | Protect a worksheet using optional protection options |
| `search-files` ·common | `excel.searchFiles()` | `--query` | 5 | Search OneDrive drive items by query to discover Excel workbook IDs |
| `sort-range` | `excel.sortRange()` | `--fields` `--item-id` `--range-type` `--worksheet` | 3 | Sort a range in a worksheet using Microsoft Graph API |
| `update-chart` | `excel.updateChart()` | `--chart-id` `--item-id` `--worksheet` | 7 | Update a chart in a worksheet using Microsoft Graph API |
| `update-chart-legend` | `excel.updateChartLegend()` | `--chart-id` `--item-id` `--worksheet` | 5 | Update formatting or position of a chart legend |
| `update-range` | `excel.updateRange()` | `--address` `--item-id` `--values` `--worksheet-id` | 2 | Update a range in a worksheet using Microsoft Graph API |
| `update-sharepoint-range` | `excel.updateSharepointRange()` | `--address` `--item-id` `--site-id` `--values` `--worksheet-id` | 1 | Update a range in a SharePoint worksheet using Microsoft Graph Sites API |
| `update-table` | `excel.updateTable()` | `--item-id` `--table-id` | 6 | Update a table in a workbook using Microsoft Graph API |
| `update-worksheet` | `excel.updateWorksheet()` | `--item-id` `--worksheet` | 5 | Update worksheet properties (name, position) in an Excel workbook using Microsoft Graph API |
| `upload-workbook` | `excel.uploadWorkbook()` | `--source-url` | 3 | Upload an external Excel file from a URL into OneDrive/SharePoint |

## 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.