Getting started

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.

terminal

orc connections list --workspace YOUR_WORKSPACE_ID --provider google-sheets --format json

Example

Subcommands

`get`

Read tabs, Tables, and column types

terminal

orc sheets get <id> <spreadsheet-id> [options]

`create`

Create a spreadsheet

terminal

orc sheets create <id> [options]

Unique options

`--locale`

Body field: locale; max 20 chars

Type: string. Optional.

terminal

orc sheets create <id> --locale <value>

`--sheet-titles`

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

Type: string. Optional.

terminal

orc sheets create <id> --sheet-titles <value>

`--time-zone`

Body field: time_zone; max 100 chars

Type: string. Optional.

terminal

orc sheets create <id> --time-zone <value>

`--title`

(required) Body field: title; max 500 chars

Type: string. Optional.

terminal

orc sheets create <id> --title <value>

`values get`

Read several ranges and Table columns

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.

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.

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.

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.

terminal

orc sheets values get <id> <spreadsheet-id> --tables <value>

`values update`

Write several ranges (preview the diff first)

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.

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.

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.

terminal

orc sheets values update <id> <spreadsheet-id> --preview <value>

`tables create`

Create a typed native Table

terminal

orc sheets tables create <id> <spreadsheet-id> [options]

Unique options

`--anchor`

Top-left cell of the header row.

Type: string. Optional.

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.

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.

terminal

orc sheets tables create <id> <spreadsheet-id> --input <value>

`--name`

(required) Body field: name; max 200 chars

Type: string. Optional.

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.

terminal

orc sheets tables create <id> <spreadsheet-id> --rows <value>

`--sheet`

(required) Existing tab title.; max 100 chars

Type: string. Optional.

terminal

orc sheets tables create <id> <spreadsheet-id> --sheet <value>

`tables rows create`

Append rows to a Table

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.

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.

terminal

orc sheets tables rows create <id> <spreadsheet-id> <table-id> --rows <value>

Examples

Inspect the structure

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

terminal

orc sheets values get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < read.json

Read ranges and Table columns

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.

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

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.

terminal

orc sheets tables create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < table.json

Create a typed Table

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.

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

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 can be used with orc sheets:

For details and examples, see global options.

​sheets

​Usage

​Subcommands

​get

​create

​Unique options

​--locale

​--sheet-titles

​--time-zone

​--title

​values get

​Unique options

​--max-rows

​--ranges

​--render

​--tables

​values update

​Unique options

​--data

​--input

​--preview

​tables create

​Unique options

​--anchor

​--columns

​--input

​--name

​--rows

​--sheet

​tables rows create

​Unique options

​--input

​--rows

​Examples

​Inspect the structure

​Read ranges and Table columns

​Preview a change, then write it

​Create a typed Table

​Append rows to a Table

​Create a spreadsheet

​Permissions

​Global Options

sheets

Usage

Subcommands

`get`

`create`

Unique options

`--locale`

`--sheet-titles`

`--time-zone`

`--title`

`values get`

Unique options

`--max-rows`

`--ranges`

`--render`

`--tables`

`values update`

Unique options

`--data`

`--input`

`--preview`

`tables create`

Unique options

`--anchor`

`--columns`

`--input`

`--name`

`--rows`

`--sheet`

`tables rows create`

Unique options

`--input`

`--rows`

Examples

Inspect the structure

Read ranges and Table columns

Preview a change, then write it

Create a typed Table

Append rows to a Table

Create a spreadsheet

Permissions

Global Options