---
title: sheets
description: Read and write Google Sheets structure, values, and native Tables.
canonical_url: https://orchestor.io/docs/en/cli/sheets
markdown_url: https://orchestor.io/docs/en/cli/sheets.md
contentType: reference
---

# sheets

`orc sheets` operates on spreadsheets that your connected Google account can access. The commands are designed so an agent does not have to guess coordinates: learn the structure, read only the values you need, preview the change, then write.

`get` returns tabs, native Tables (name, range, column names, and column types), and named ranges without reading cell values. `values get` reads several A1 ranges and Table columns in one Google request; reference a Table by name and receive only the columns you ask for. `values update` with `preview` returns the before/after diff of the cells that would change without writing. `tables create` creates a typed native Table, and `tables rows create` appends rows inside the Table, above any footer.

Writes are not idempotent. If a write times out, its outcome is unknown: read the target range before retrying. Appending rows is not an upsert.

## Usage

Find the connection ID. The spreadsheet ID is the part of the sheet URL between /d/ and /edit.

```bash title="terminal"
orc connections list --workspace YOUR_WORKSPACE_ID --provider google-sheets --format json
```

*Example*

## Subcommands

### `get`

Read tabs, Tables, and column types

```bash title="terminal"
orc sheets get <id> <spreadsheet-id> [options]
```

### `create`

Create a spreadsheet

```bash title="terminal"
orc sheets create <id> [options]
```

#### Unique options

##### `--locale`

Body field: locale; max 20 chars

Type: `string`. Optional.

```bash title="terminal"
orc sheets create <id> --locale <value>
```

##### `--sheet-titles`

Tab titles to create. Defaults to one Google-named tab.; csv

Type: `string`. Optional.

```bash title="terminal"
orc sheets create <id> --sheet-titles <value>
```

##### `--time-zone`

Body field: time_zone; max 100 chars

Type: `string`. Optional.

```bash title="terminal"
orc sheets create <id> --time-zone <value>
```

##### `--title`

(required) Body field: title; max 500 chars

Type: `string`. Optional.

```bash title="terminal"
orc sheets create <id> --title <value>
```

### `values get`

Read several ranges and Table columns

```bash title="terminal"
orc sheets values get <id> <spreadsheet-id> [options]
```

#### Unique options

##### `--max-rows`

Row cap per range or table. truncated reports when rows were cut.

Type: `number`. Optional.

```bash title="terminal"
orc sheets values get <id> <spreadsheet-id> --max-rows <value>
```

##### `--ranges`

A1 ranges to read. On the CLI, pass several as comma-separated values.; csv

Type: `string`. Optional.

```bash title="terminal"
orc sheets values get <id> <spreadsheet-id> --ranges <value>
```

##### `--render`

unformatted returns exact numbers; formatted returns displayed text; formula returns formulas instead of results.; enum: unformatted|formatted|formula

Type: `string`. Optional.

```bash title="terminal"
orc sheets values get <id> <spreadsheet-id> --render <value>
```

##### `--tables`

Body field: tables; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc sheets values get <id> <spreadsheet-id> --tables <value>
```

### `values update`

Write several ranges (preview the diff first)

```bash title="terminal"
orc sheets values update <id> <spreadsheet-id> [options]
```

#### Unique options

##### `--data`

(required) Body field: data; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc sheets values update <id> <spreadsheet-id> --data <value>
```

##### `--input`

raw stores values as given. user_entered parses values like the Sheets UI, including formulas starting with "=".; enum: raw|user_entered

Type: `string`. Optional.

```bash title="terminal"
orc sheets values update <id> <spreadsheet-id> --input <value>
```

##### `--preview`

Read the target cells and return the before/after diff without writing.

Type: `string`. Optional.

```bash title="terminal"
orc sheets values update <id> <spreadsheet-id> --preview <value>
```

### `tables create`

Create a typed native Table

```bash title="terminal"
orc sheets tables create <id> <spreadsheet-id> [options]
```

#### Unique options

##### `--anchor`

Top-left cell of the header row.

Type: `string`. Optional.

```bash title="terminal"
orc sheets tables create <id> <spreadsheet-id> --anchor <value>
```

##### `--columns`

(required) Body field: columns; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc sheets tables create <id> <spreadsheet-id> --columns <value>
```

##### `--input`

raw stores values as given. user_entered parses values like the Sheets UI, including formulas starting with "=".; enum: raw|user_entered

Type: `string`. Optional.

```bash title="terminal"
orc sheets tables create <id> <spreadsheet-id> --input <value>
```

##### `--name`

(required) Body field: name; max 200 chars

Type: `string`. Optional.

```bash title="terminal"
orc sheets tables create <id> <spreadsheet-id> --name <value>
```

##### `--rows`

Rows as arrays in column order, or objects keyed by column name. Missing keys become empty cells; unknown keys are rejected.; csv

Type: `string`. Optional.

```bash title="terminal"
orc sheets tables create <id> <spreadsheet-id> --rows <value>
```

##### `--sheet`

(required) Existing tab title.; max 100 chars

Type: `string`. Optional.

```bash title="terminal"
orc sheets tables create <id> <spreadsheet-id> --sheet <value>
```

### `tables rows create`

Append rows to a Table

```bash title="terminal"
orc sheets tables rows create <id> <spreadsheet-id> <table-id> [options]
```

#### Unique options

##### `--input`

raw stores values as given. user_entered parses values like the Sheets UI, including formulas starting with "=".; enum: raw|user_entered

Type: `string`. Optional.

```bash title="terminal"
orc sheets tables rows create <id> <spreadsheet-id> <table-id> --input <value>
```

##### `--rows`

(required) Rows as arrays in column order, or objects keyed by column name. Missing keys become empty cells; unknown keys are rejected.; csv

Type: `string`. Optional.

```bash title="terminal"
orc sheets tables rows create <id> <spreadsheet-id> <table-id> --rows <value>
```

## Examples

### Inspect the structure

```bash title="terminal"
orc sheets get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --format json
```

*Inspect the structure*

### Read ranges and Table columns

Save the following JSON as read.json. `render` is `unformatted` (exact numbers), `formatted` (displayed text), or `formula` (formulas).

```bash title="terminal"
orc sheets values get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < read.json
```

*Read ranges and Table columns*

```json title="read.json"
{
  "ranges": ["Metrics!A1:A3"],
  "tables": [{ "table": "Weekly", "columns": ["week", "sessions"] }],
  "render": "unformatted",
  "max_rows": 500
}
```

### Preview a change, then write it

Run with `preview` set to `true` to see the diff, then set it to `false` to write. `null` leaves a cell unchanged and an empty string clears it. Use `input: user_entered` to write formulas.

```bash title="terminal"
orc sheets values update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < write.json
```

*Preview a change, then write it*

```json title="write.json"
{
  "data": [{ "range": "Metrics!C3:C4", "values": [[1200], ["=SUM(C2:C3)"]] }],
  "input": "user_entered",
  "preview": true
}
```

### Create a typed Table

Writes the header and rows and creates the Table in one atomic batch. Dates accept ISO text (YYYY-MM-DD). Values that do not match a column type are rejected before anything is sent.

```bash title="terminal"
orc sheets tables create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < table.json
```

*Create a typed Table*

```json title="table.json"
{
  "name": "Weekly",
  "sheet": "Metrics",
  "anchor": "A1",
  "columns": [
    { "name": "week", "type": "date" },
    { "name": "channel", "type": "text" },
    { "name": "sessions", "type": "number" }
  ],
  "rows": [{ "week": "2026-09-28", "channel": "organic", "sessions": 1200 }]
}
```

### Append rows to a Table

Reference the Table by ID or name. Unknown column names are rejected.

```bash title="terminal"
echo '{"rows":[{"week":"2026-10-05","channel":"organic","sessions":1350}]}' | orc sheets tables rows create YOUR_CONNECTION_ID SPREADSHEET_ID Weekly --workspace YOUR_WORKSPACE_ID --stdin --format json
```

*Append rows to a Table*

### Create a spreadsheet

```bash title="terminal"
orc sheets create YOUR_CONNECTION_ID --workspace YOUR_WORKSPACE_ID --title 'AI visibility report' --sheet-titles Summary,Weekly --format json
```

*Create a spreadsheet*

## Permissions

Connect Google Sheets in Settings → Integrations and grant the `spreadsheets` scope. The spreadsheet must be shared with the connected Google account. Orchestor requires authentication and an accessible workspace.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc sheets`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

[Documentation index](https://orchestor.io/docs/llms.txt)