sheets
orc sheets tabs update sht_... TAB_ID --sort-column COL --sort-direction asc|desc saves a single-column sort. --filter-column COL --filter-value V saves one substring filter. COL accepts a column ID or unambiguous title. Use --clear-sort and --clear-filter to clear settings. Setting and clearing the same field together is rejected. Unknown or deleted columns return 400 from the API. Omitted settings are retained; writes return the full sheet. The CLI fetches omitted --updated-at tokens and never retries stale 409 writes. These flags return unsupported_by_backend with a Google connection. Filter values are excluded from logs and dry-run diagnostics.
orc sheets rows list|create|update|delete sht_... TAB_ID [ROW_ID] manages in-house rows. Google connection IDs return unsupported_by_backend. rows list follows stored order with cursor pagination: --limit defaults to 100 and accepts at most 1000; pass the response's next_cursor as --cursor. Responses retain data, next_cursor and the sheet updated_at. --as csv, --max-rows and --sample head_and_tail format and sample the requested page. Global --readonly and --wrap-untrusted use the same helpers as Google values reads. --page-all streams all pages as NDJSON and cannot be combined with --as csv.
Writes read JSON through --stdin and send one atomic batch. Create accepts { "values": { "COLUMN_ID": "text" }, "before_row_id": "ROW_ID" } with optional insertion position. Update accepts ROW_ID and { "values": { "COLUMN_ID": null } }. Delete accepts ROW_ID or { "row_id": "ROW_ID" }. Any write command also accepts { "operations": [{ "op": "create", "values": {} }, { "op": "update", "row_id": "ROW_ID", "values": {} }, { "op": "delete", "row_id": "OTHER_ROW_ID" }] } for a mixed batch. The server generates row IDs. --preview writes nothing and returns { preview: true, changes: [{ row_id, column_id, before, after }], created, deleted }; created and deleted contain row ID arrays. Writes return the full sheet. If --updated-at is omitted, the CLI fetches the current token. Stale tokens return 409; unknown sheets, tabs and rows return 404.
Value keys accept column IDs or unambiguous titles. Ambiguous or unknown columns and invalid types reject the whole batch with 400 and row_ref, column_id, reason. Number/currency require finite numbers; date a valid YYYY-MM-DD; url an absolute HTTP(S) URL; email an email-shaped string; checkbox a boolean; select a configured option; multi-select an array of configured options; text/image a string. Writes never coerce values. Updates merge specified cells; null removes a cell key. Unknown rows are never upserted. Writes are not idempotent. If the outcome is unknown, re-read before retrying.
orc sheets columns list/create/update/delete sht_... TAB_ID [COLUMN_ID] manages in-house columns only. Passing a Google connection and spreadsheet ID returns unsupported_by_backend. Create requires --title and --type. The ten types are text, number, currency, date, url, email, image, checkbox, select, and multi-select. --options A,B is valid only for select and multi-select. --currency-code JPY is valid only for currency and requires the three-uppercase-letter ISO 4217 format. Set --description, --color, --pinned true/false, --hidden true/false, and the zero-based --position. The server issues column IDs and each write returns the full updated sheet. The CLI fetches omitted --updated-at tokens. Stale writes return 409; unknown sheets, tabs, or columns return 404. The CLI never retries stale writes.
Deleting a column removes its definition and every row value, and clears sort and filter references. Type changes retain compatible values and remove incompatible cell keys. Text stringifies values and joins arrays with comma-space. Number and currency retain finite numbers and parse nonblank finite numeric strings. Checkbox accepts booleans, true/false strings, and 1/0 numbers or strings. Date requires a valid YYYY-MM-DD string; URL and image require HTTP(S) URLs; email requires an email-shaped string. Select retains an allowed string or a single-element array containing one. Multi-select wraps strings in arrays and removes entries outside the options. Editing options applies the same selection rules.
Use orc sheets list, create --title NAME, and get/update/delete sht_... for workspace-stored Space sheets. Creation returns one empty tab. Pass the last response's updated_at as --updated-at when updating or deleting. Stale writes return 409 without changes. Update supports --title, --pinned true/false, --sort-position, --archived true/false, and the whole --tabs document. In-house sheets need workspace access but no Google connection. Google commands keep their existing arguments: get CONNECTION_ID SPREADSHEET_ID and create CONNECTION_ID --title NAME. Google subcommands such as values, tabs, tables, files, and schemas retain their existing behavior and connection requirements.
orc sheets tabs create sht_... --title NAME adds an empty tab. tabs update sht_... TAB_ID accepts --title, --index (a zero-based position among all tabs, including hidden and deleted tabs), --hidden true/false, and --deleted true/false. tabs delete sht_... TAB_ID --yes soft-deletes a tab; tabs update ... --deleted false restores it. Also pass --hidden false to show a restored hidden tab. At least one tab must remain visible and not deleted. On create, use --before-tab-id TAB_ID or --index to choose the insertion position. The server assigns tab IDs, and every write returns the updated sheet. If you omit --updated-at, the CLI fetches the current token with GET. Stale tokens return 409 and are never retried automatically. --dry-run can use GET to resolve the token or insertion position, but sends no write. Google-only frozen row/column and grid-size flags return unsupported_by_backend for in-house 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.
Everyday tab, row/column, and range operations have named commands. tabs create/update/delete and tabs copies create add, rename, reorder, freeze, delete, and duplicate tabs; dimensions create/update/delete insert, resize, and delete rows or columns; values create/delete append rows after a range and clear ranges. Deleting rows or columns shrinks intersecting native Tables in the same batch and refuses a delete that would empty a Table. Positions are 1-based; tabs are referenced by title or numeric sheet ID.
Formatting, merges, and range operations have named commands too. formats update applies cell and number formats, merges create/delete merge and unmerge, ranges copies create copies (a destination larger than the source tiles it, filling formulas down or across), ranges moves create moves, ranges sorts create sorts, replacements create finds and replaces, and named-ranges list/create/update/delete manage named ranges. Ranges are A1 notation with a sheet name (Sheet1!A1:B2) or a named range name.
Validation, conditional formats, filters, banding, charts, and Tables have named commands too. validations update/delete manage dropdown, checkbox, and condition rules; conditional-formats list/create/delete manage conditional formats; filters update/delete set and clear the basic filter (replacing one requires replace); bandings list/create/delete manage alternating colors; charts list/create/update/delete manage charts; tables update/delete rename, resize, or delete Tables. Deleting a Table also deletes every cell in its range, so it runs only with discard_data=true.
Cell links and notes have commands too: links list/update read and write links, including several links in one cell, and notes list/update read and write notes.
Some output is shaped for agents. get --include-errors true returns error cells such as #REF! along with the structure, and as: csv on values get returns one CSV string per range; when rows exceed max_rows, sample: head_and_tail keeps the first and last rows. Use the global --readonly option to block writes, and --wrap-untrusted when an AI model will read the fetched content.
Some operations use Drive access: files list lists and searches spreadsheets, exports get exports to XLSX, PDF, CSV, TSV, or ODS (save with --output; CSV and TSV contain the first tab only), and copies create copies a whole spreadsheet. A connection authorized without Drive is asked to reconnect.
For operations without a named command, a generic surface reaches every Google Sheets API v4 method and batchUpdate request. api get calls read-only methods, api update calls mutating methods, and batch-requests create applies batchUpdate requests such as formatting, charts, filters, and protected ranges. List the methods, request types, and type definitions with schemas list and schemas get. Only names in the pinned Discovery revision are accepted; anything else is rejected before sending.
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.
orc connections list --workspace YOUR_WORKSPACE_ID --provider google-workspace --format jsonExample
Subcommands
columns list
List typed in-house columns
orc sheets columns list [sheet-id] [tab-id] [options]columns create
Create typed in-house columns
orc sheets columns create [sheet-id] [tab-id] [options]Unique options
--color
Body field: color
Type: string. Optional.
orc sheets columns create --color <value>--currency-code
Body field: currencyCode
Type: string. Optional.
orc sheets columns create --currency-code <value>--description
Body field: description
Type: string. Optional.
orc sheets columns create --description <value>Body field: hidden
Type: string. Optional.
orc sheets columns create --hidden <value>--options
Body field: options; csv
Type: string. Optional.
orc sheets columns create --options <value>--pinned
Body field: pinned
Type: string. Optional.
orc sheets columns create --pinned <value>--position
Body field: position
Type: number. Optional.
orc sheets columns create --position <value>--title
(required) Body field: title; max 100 chars
Type: string. Optional.
orc sheets columns create --title <value>--type
(required) Body field: type; enum: text|number|currency|url|domain|date|timestamp|email|image|checkbox|select|multi-select
Type: string. Optional.
orc sheets columns create --type <value>--updated-at
(required) Body field: updated_at
Type: string. Optional.
orc sheets columns create --updated-at <value>--width
Body field: width
Type: number. Optional.
orc sheets columns create --width <value>columns update
Update typed in-house columns
orc sheets columns update [sheet-id] [tab-id] [column-id] [options]Unique options
--color
Body field: color
Type: string. Optional.
orc sheets columns update --color <value>--currency-code
Body field: currencyCode
Type: string. Optional.
orc sheets columns update --currency-code <value>--description
Body field: description
Type: string. Optional.
orc sheets columns update --description <value>Body field: hidden
Type: string. Optional.
orc sheets columns update --hidden <value>--options
Body field: options; csv
Type: string. Optional.
orc sheets columns update --options <value>--pinned
Body field: pinned
Type: string. Optional.
orc sheets columns update --pinned <value>--position
Body field: position
Type: number. Optional.
orc sheets columns update --position <value>--title
Body field: title; max 100 chars
Type: string. Optional.
orc sheets columns update --title <value>--type
Body field: type; enum: text|number|currency|url|domain|date|timestamp|email|image|checkbox|select|multi-select
Type: string. Optional.
orc sheets columns update --type <value>--updated-at
(required) Body field: updated_at
Type: string. Optional.
orc sheets columns update --updated-at <value>--width
Body field: width
Type: number. Optional.
orc sheets columns update --width <value>columns delete
Delete typed in-house columns
orc sheets columns delete [sheet-id] [tab-id] [column-id] [options]Unique options
--updated-at
value
Type: string. Optional.
orc sheets columns delete --updated-at <value>list
List in-house Space sheets
orc sheets list [options]update
Rename, pin, order, archive or edit an in-house Space sheet
orc sheets update <sheet-id> [options]Unique options
--archived
Body field: archived
Type: string. Optional.
orc sheets update <sheet-id> --archived <value>--pinned
Body field: pinned
Type: string. Optional.
orc sheets update <sheet-id> --pinned <value>--sort-position
Body field: sort_position
Type: number. Optional.
orc sheets update <sheet-id> --sort-position <value>--tabs
Body field: tabs; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc sheets update <sheet-id> --tabs <value>--title
Body field: title; max 100 chars
Type: string. Optional.
orc sheets update <sheet-id> --title <value>--updated-at
(required) Body field: updated_at
Type: string. Optional.
orc sheets update <sheet-id> --updated-at <value>delete
Delete an in-house Space sheet
orc sheets delete <sheet-id> [options]Unique options
--updated-at
value
Type: string. Required.
orc sheets delete <sheet-id> --updated-at <value>get
Read tabs, Tables, and column types
orc sheets get <id> [spreadsheet-id] [options]Unique options
--include-errors
Also scan every tab for error cells (#REF!, #N/A, #DIV/0!, #VALUE!, #NAME?, #NUM!, #ERROR!).; enum: true|false
Type: string. Optional.
orc sheets get <id> --include-errors <value>create
Create a spreadsheet
orc sheets create [id] [options]Unique options
--locale
Body field: locale; max 20 chars
Type: string. Optional.
orc sheets create --locale <value>--sheet-titles
Tab titles to create. Defaults to one Google-named tab.; csv
Type: string. Optional.
orc sheets create --sheet-titles <value>--time-zone
Body field: time_zone; max 100 chars
Type: string. Optional.
orc sheets create --time-zone <value>--title
(required) Body field: title; max 500 chars
Type: string. Optional.
orc sheets create --title <value>values get
Read several ranges and Table columns
orc sheets values get <id> <spreadsheet-id> [options]Unique options
--as
rows returns typed 2D values; csv returns one compact CSV string per range for reading.; enum: rows|csv
Type: string. Optional.
orc sheets values get <id> <spreadsheet-id> --as <value>--max-rows
Row cap per range or table. truncated reports when rows were cut.
Type: number. Optional.
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.
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.
orc sheets values get <id> <spreadsheet-id> --render <value>--sample
When rows exceed max_rows: head keeps the first rows; head_and_tail keeps the first and last halves.; enum: head|head_and_tail
Type: string. Optional.
orc sheets values get <id> <spreadsheet-id> --sample <value>--tables
Body field: tables; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc sheets values get <id> <spreadsheet-id> --tables <value>values update
Write several ranges (preview the diff first)
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.
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.
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.
orc sheets values update <id> <spreadsheet-id> --preview <value>tables create
Create a typed native Table
orc sheets tables create <id> <spreadsheet-id> [options]Unique options
--anchor
Top-left cell of the header row.
Type: string. Optional.
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.
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.
orc sheets tables create <id> <spreadsheet-id> --input <value>--name
(required) Body field: name; max 200 chars
Type: string. Optional.
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.
orc sheets tables create <id> <spreadsheet-id> --rows <value>--sheet
(required) Existing tab title.; max 100 chars
Type: string. Optional.
orc sheets tables create <id> <spreadsheet-id> --sheet <value>tables rows create
Append rows to a Table
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.
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.
orc sheets tables rows create <id> <spreadsheet-id> <table-id> --rows <value>tabs create
Add a tab
orc sheets tabs create <id> [spreadsheet-id] [options]Unique options
--columns
Body field: columns
Type: number. Optional.
orc sheets tabs create <id> --columns <value>--index
Zero-based position. Defaults to the end.
Type: number. Optional.
orc sheets tabs create <id> --index <value>--rows
Body field: rows
Type: number. Optional.
orc sheets tabs create <id> --rows <value>--title
(required) Body field: title; max 100 chars
Type: string. Optional.
orc sheets tabs create <id> --title <value>--before-tab-id
Body field: before_tab_id; max 256 chars
Type: string. Optional.
orc sheets tabs create <id> --before-tab-id <value>--updated-at
(required) Body field: updated_at
Type: string. Optional.
orc sheets tabs create <id> --updated-at <value>tabs update
Rename, move, hide, or freeze a tab
orc sheets tabs update <id> [spreadsheet-id] [tab] [options]Unique options
--frozen-columns
Columns to freeze; 0 unfreezes.
Type: number. Optional.
orc sheets tabs update <id> --frozen-columns <value>--frozen-rows
Rows to freeze; 0 unfreezes.
Type: number. Optional.
orc sheets tabs update <id> --frozen-rows <value>Body field: hidden
Type: string. Optional.
orc sheets tabs update <id> --hidden <value>--index
Destination zero-based position.
Type: number. Optional.
orc sheets tabs update <id> --index <value>--title
Body field: title; max 100 chars
Type: string. Optional.
orc sheets tabs update <id> --title <value>--deleted
Body field: deleted
Type: string. Optional.
orc sheets tabs update <id> --deleted <value>--position
Body field: position
Type: number. Optional.
orc sheets tabs update <id> --position <value>--sort
Body field: sort; (JSON object, e.g. '{"custom_id":"x"}'); (use "null" or "reset" to clear)
Type: string. Optional.
orc sheets tabs update <id> --sort <value>--updated-at
(required) Body field: updated_at
Type: string. Optional.
orc sheets tabs update <id> --updated-at <value>--sort-column
In-house sheet tab: sort-column
Type: string. Optional.
orc sheets tabs update <id> --sort-column <value>--sort-direction
In-house sheet tab: sort-direction
Type: string. Optional.
orc sheets tabs update <id> --sort-direction <value>--clear-sort
In-house sheet tab: clear-sort
Type: boolean. Optional.
orc sheets tabs update <id> --clear-sort--filter-column
In-house sheet tab: filter-column
Type: string. Optional.
orc sheets tabs update <id> --filter-column <value>--filter-value
In-house sheet tab: filter-value
Type: string. Optional.
orc sheets tabs update <id> --filter-value <value>--clear-filter
In-house sheet tab: clear-filter
Type: boolean. Optional.
orc sheets tabs update <id> --clear-filtertabs delete
Delete a tab
orc sheets tabs delete <id> [spreadsheet-id] [tab] [options]Unique options
--updated-at
value
Type: string. Optional.
orc sheets tabs delete <id> --updated-at <value>tabs copies create
Duplicate a tab or copy it to another spreadsheet
orc sheets tabs copies create <id> <spreadsheet-id> <tab> [options]Unique options
--destination-spreadsheet-id
Copy into another spreadsheet (Sheets copyTo). Defaults to this spreadsheet.
Type: string. Optional.
orc sheets tabs copies create <id> <spreadsheet-id> <tab> --destination-spreadsheet-id <value>--index
Zero-based position for an in-spreadsheet copy. Defaults to right after the source.
Type: number. Optional.
orc sheets tabs copies create <id> <spreadsheet-id> <tab> --index <value>--title
Title of the copy. Defaults to the Google "Copy of" name.; max 100 chars
Type: string. Optional.
orc sheets tabs copies create <id> <spreadsheet-id> <tab> --title <value>dimensions create
Insert rows or columns
orc sheets dimensions create <id> <spreadsheet-id> [options]Unique options
--after
Body field: after
Type: string. Optional.
orc sheets dimensions create <id> <spreadsheet-id> --after <value>--count
Body field: count
Type: number. Optional.
orc sheets dimensions create <id> <spreadsheet-id> --count <value>--dimension
(required) Body field: dimension; enum: rows|columns
Type: string. Optional.
orc sheets dimensions create <id> <spreadsheet-id> --dimension <value>--inherit-from-before
Inherit formatting from the row/column before. Defaults to true with after, false otherwise.
Type: string. Optional.
orc sheets dimensions create <id> <spreadsheet-id> --inherit-from-before <value>--start
(required) 1-based row or column number to insert before (or after with after=true). For columns, 1=A.
Type: number. Optional.
orc sheets dimensions create <id> <spreadsheet-id> --start <value>--tab
(required) Tab title or numeric sheet ID.; max 100 chars
Type: string. Optional.
orc sheets dimensions create <id> <spreadsheet-id> --tab <value>dimensions update
Resize, auto-fit, or hide rows or columns
orc sheets dimensions update <id> <spreadsheet-id> [options]Unique options
--auto-resize
Fit to content.
Type: string. Optional.
orc sheets dimensions update <id> <spreadsheet-id> --auto-resize <value>--dimension
(required) Body field: dimension; enum: rows|columns
Type: string. Optional.
orc sheets dimensions update <id> <spreadsheet-id> --dimension <value>--end
(required) Body field: end
Type: number. Optional.
orc sheets dimensions update <id> <spreadsheet-id> --end <value>Body field: hidden
Type: string. Optional.
orc sheets dimensions update <id> <spreadsheet-id> --hidden <value>--size
Row height or column width in pixels.
Type: number. Optional.
orc sheets dimensions update <id> <spreadsheet-id> --size <value>--start
(required) Body field: start
Type: number. Optional.
orc sheets dimensions update <id> <spreadsheet-id> --start <value>--tab
(required) Tab title or numeric sheet ID.; max 100 chars
Type: string. Optional.
orc sheets dimensions update <id> <spreadsheet-id> --tab <value>dimensions delete
Delete rows or columns, keeping Tables intact
orc sheets dimensions delete <id> <spreadsheet-id> [options]Unique options
--dimension
(required) Body field: dimension; enum: rows|columns
Type: string. Optional.
orc sheets dimensions delete <id> <spreadsheet-id> --dimension <value>--end
(required) Last 1-based row/column to delete (inclusive).
Type: number. Optional.
orc sheets dimensions delete <id> <spreadsheet-id> --end <value>--start
(required) First 1-based row/column to delete (inclusive).
Type: number. Optional.
orc sheets dimensions delete <id> <spreadsheet-id> --start <value>--tab
(required) Tab title or numeric sheet ID.; max 100 chars
Type: string. Optional.
orc sheets dimensions delete <id> <spreadsheet-id> --tab <value>values create
Append rows after a range
orc sheets values create <id> <spreadsheet-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.
orc sheets values create <id> <spreadsheet-id> --input <value>--insert
insert_rows adds new rows; overwrite writes into existing empty rows.; enum: insert_rows|overwrite
Type: string. Optional.
orc sheets values create <id> <spreadsheet-id> --insert <value>--range
(required) Range whose table-like data the rows follow, e.g. Log!A:D or a named range.; max 500 chars
Type: string. Optional.
orc sheets values create <id> <spreadsheet-id> --range <value>--values
(required) Body field: values; JSON array of arrays (use --stdin for large resources)
Type: string. Optional.
orc sheets values create <id> <spreadsheet-id> --values <value>values delete
Clear range values
orc sheets values delete <id> <spreadsheet-id> [options]Unique options
--ranges
(required) Body field: ranges; csv
Type: string. Optional.
orc sheets values delete <id> <spreadsheet-id> --ranges <value>formats update
Set cell and number formats
orc sheets formats update <id> <spreadsheet-id> [options]Unique options
--cell-format
Sheets API CellFormat, e.g. {"textFormat":{"bold":true},"backgroundColorStyle":{...}}. Run orc sheets schemas get CellFormat.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets formats update <id> <spreadsheet-id> --cell-format <value>--field-mask
Field mask; textFormat.bold and userEnteredFormat.textFormat.bold are both accepted. Defaults to the keys you send.; max 1000 chars
Type: string. Optional.
orc sheets formats update <id> <spreadsheet-id> --field-mask <value>--number-format
Body field: number_format; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets formats update <id> <spreadsheet-id> --number-format <value>--range
(required) A1 range with a sheet name (Sheet1!A1:B2) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets formats update <id> <spreadsheet-id> --range <value>merges create
Merge cells
orc sheets merges create <id> <spreadsheet-id> [options]Unique options
--range
(required) A1 range with a sheet name (Sheet1!A1:B2) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets merges create <id> <spreadsheet-id> --range <value>--type
Body field: type; enum: all|columns|rows
Type: string. Optional.
orc sheets merges create <id> <spreadsheet-id> --type <value>merges delete
Unmerge cells
orc sheets merges delete <id> <spreadsheet-id> [options]Unique options
--range
(required) A1 range with a sheet name (Sheet1!A1:B2) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets merges delete <id> <spreadsheet-id> --range <value>ranges copies create
Copy a range (fill formulas down)
orc sheets ranges copies create <id> <spreadsheet-id> [options]Unique options
--destination
(required) Destination range. A destination larger than the source tiles the source, filling formulas down or across with relative references adjusted.; max 500 chars
Type: string. Optional.
orc sheets ranges copies create <id> <spreadsheet-id> --destination <value>--paste-type
Body field: paste_type; enum: normal|values|format|formula|no_borders|data_validation|conditional_formatting
Type: string. Optional.
orc sheets ranges copies create <id> <spreadsheet-id> --paste-type <value>--source
(required) A1 range with a sheet name (Sheet1!A1:B2) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets ranges copies create <id> <spreadsheet-id> --source <value>--transpose
Body field: transpose
Type: string. Optional.
orc sheets ranges copies create <id> <spreadsheet-id> --transpose <value>ranges moves create
Move a range
orc sheets ranges moves create <id> <spreadsheet-id> [options]Unique options
--destination
(required) Top-left cell of the destination, e.g. Sheet1!D1.; max 500 chars
Type: string. Optional.
orc sheets ranges moves create <id> <spreadsheet-id> --destination <value>--paste-type
Body field: paste_type; enum: normal|values|format|formula|no_borders|data_validation|conditional_formatting
Type: string. Optional.
orc sheets ranges moves create <id> <spreadsheet-id> --paste-type <value>--source
(required) A1 range with a sheet name (Sheet1!A1:B2) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets ranges moves create <id> <spreadsheet-id> --source <value>ranges sorts create
Sort a range
orc sheets ranges sorts create <id> <spreadsheet-id> [options]Unique options
--range
(required) Range to sort, without the header row, e.g. Data!A2:F200.; max 500 chars
Type: string. Optional.
orc sheets ranges sorts create <id> <spreadsheet-id> --range <value>--sort
(required) Body field: sort; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc sheets ranges sorts create <id> <spreadsheet-id> --sort <value>replacements create
Find and replace
orc sheets replacements create <id> <spreadsheet-id> [options]Unique options
--find
(required) Body field: find; max 10000 chars
Type: string. Optional.
orc sheets replacements create <id> <spreadsheet-id> --find <value>--include-formulas
Also search inside formulas.
Type: string. Optional.
orc sheets replacements create <id> <spreadsheet-id> --include-formulas <value>--match-case
Body field: match_case
Type: string. Optional.
orc sheets replacements create <id> <spreadsheet-id> --match-case <value>--match-entire-cell
Body field: match_entire_cell
Type: string. Optional.
orc sheets replacements create <id> <spreadsheet-id> --match-entire-cell <value>--range
Limit to one range.; max 500 chars
Type: string. Optional.
orc sheets replacements create <id> <spreadsheet-id> --range <value>--regex
Body field: regex
Type: string. Optional.
orc sheets replacements create <id> <spreadsheet-id> --regex <value>--replacement
(required) Body field: replacement; max 10000 chars
Type: string. Optional.
orc sheets replacements create <id> <spreadsheet-id> --replacement <value>--tab
Limit to one tab (title or sheet ID).; max 100 chars
Type: string. Optional.
orc sheets replacements create <id> <spreadsheet-id> --tab <value>named-ranges list
List named ranges
orc sheets named-ranges list <id> <spreadsheet-id> [options]named-ranges create
Create a named range
orc sheets named-ranges create <id> <spreadsheet-id> [options]Unique options
--name
(required) Body field: name; max 250 chars
Type: string. Optional.
orc sheets named-ranges create <id> <spreadsheet-id> --name <value>--range
(required) A1 range with a sheet name, e.g. Sheet1!A1:B2 or Sheet1!A:C.; max 500 chars
Type: string. Optional.
orc sheets named-ranges create <id> <spreadsheet-id> --range <value>named-ranges update
Update a named range
orc sheets named-ranges update <id> <spreadsheet-id> <named-range> [options]Unique options
--name
Body field: name; max 250 chars
Type: string. Optional.
orc sheets named-ranges update <id> <spreadsheet-id> <named-range> --name <value>--range
A1 range with a sheet name (Sheet1!A1:B2) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets named-ranges update <id> <spreadsheet-id> <named-range> --range <value>named-ranges delete
Delete a named range
orc sheets named-ranges delete <id> <spreadsheet-id> <named-range> [options]validations update
Set data validation
orc sheets validations update <id> <spreadsheet-id> [options]Unique options
--condition-type
(required) ONE_OF_LIST makes a dropdown; BOOLEAN a checkbox.; enum: ONE_OF_LIST|ONE_OF_RANGE|BOOLEAN|NUMBER_BETWEEN|NUMBER_NOT_BETWEEN|NUMBER_GREATER|NUMBER_GREATER_THAN_EQ|NUMBER_LESS|NUMBER_LESS_THAN_EQ|NUMBER_EQ|NUMBER_NOT_EQ|TEXT_CONTAINS|TEXT_NOT_CONTAINS|TEXT_EQ|TEXT_IS_EMAIL|TEXT_IS_URL|DATE_EQ|DATE_BEFORE|DATE_AFTER|DATE_ON_OR_BEFORE|DATE_ON_OR_AFTER|DATE_BETWEEN|DATE_NOT_BETWEEN|DATE_IS_VALID|CUSTOM_FORMULA
Type: string. Optional.
orc sheets validations update <id> <spreadsheet-id> --condition-type <value>--filtered-rows-included
Also apply to filtered rows; needed for table-managed dropdown columns.
Type: string. Optional.
orc sheets validations update <id> <spreadsheet-id> --filtered-rows-included <value>--input-message
Body field: input_message; max 1000 chars
Type: string. Optional.
orc sheets validations update <id> <spreadsheet-id> --input-message <value>--range
(required) A1 range with a sheet name (Sheet1!A2:A) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets validations update <id> <spreadsheet-id> --range <value>--show-custom-ui
Show the dropdown or checkbox UI where supported.
Type: string. Optional.
orc sheets validations update <id> <spreadsheet-id> --show-custom-ui <value>--strict
Reject invalid input instead of showing a warning.
Type: string. Optional.
orc sheets validations update <id> <spreadsheet-id> --strict <value>--values
Condition values: the list items, the bounds, or one value. ONE_OF_RANGE takes a range; CUSTOM_FORMULA a formula starting with =.; csv
Type: string. Optional.
orc sheets validations update <id> <spreadsheet-id> --values <value>validations delete
Clear data validation
orc sheets validations delete <id> <spreadsheet-id> [options]Unique options
--filtered-rows-included
Body field: filtered_rows_included
Type: string. Optional.
orc sheets validations delete <id> <spreadsheet-id> --filtered-rows-included <value>--range
(required) A1 range with a sheet name (Sheet1!A2:A) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets validations delete <id> <spreadsheet-id> --range <value>conditional-formats list
List conditional formats
orc sheets conditional-formats list <id> <spreadsheet-id> [options]Unique options
--tab
Only this tab (title or sheet ID).; max 100 chars
Type: string. Optional.
orc sheets conditional-formats list <id> <spreadsheet-id> --tab <value>conditional-formats create
Add a conditional format
orc sheets conditional-formats create <id> <spreadsheet-id> [options]Unique options
--cell-format
CellFormat applied when the rule matches, e.g. {"backgroundColorStyle":{"rgbColor":{"red":1}}}.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets conditional-formats create <id> <spreadsheet-id> --cell-format <value>--expression
Comparison value, or a formula starting with = for custom_formula.; max 10000 chars
Type: string. Optional.
orc sheets conditional-formats create <id> <spreadsheet-id> --expression <value>--gradient-rule
Sheets GradientRule for a color scale instead of type/expression.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets conditional-formats create <id> <spreadsheet-id> --gradient-rule <value>--index
Priority position; 0 is evaluated first.
Type: number. Optional.
orc sheets conditional-formats create <id> <spreadsheet-id> --index <value>--range
(required) A1 range with a sheet name (Sheet1!A2:A) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets conditional-formats create <id> <spreadsheet-id> --range <value>--type
Body field: type; enum: text_eq|text_contains|text_starts_with|text_ends_with|number_eq|number_gt|number_gte|number_lt|number_lte|blank|not_blank|custom_formula
Type: string. Optional.
orc sheets conditional-formats create <id> <spreadsheet-id> --type <value>conditional-formats delete
Remove conditional formats
orc sheets conditional-formats delete <id> <spreadsheet-id> [options]Unique options
--all
Body field: all
Type: string. Optional.
orc sheets conditional-formats delete <id> <spreadsheet-id> --all <value>--index
Body field: index
Type: number. Optional.
orc sheets conditional-formats delete <id> <spreadsheet-id> --index <value>--tab
(required) Tab title or numeric sheet ID.; max 100 chars
Type: string. Optional.
orc sheets conditional-formats delete <id> <spreadsheet-id> --tab <value>filters update
Set the basic filter
orc sheets filters update <id> <spreadsheet-id> [options]Unique options
--criteria
Sheets FilterSpec objects, e.g. [{"columnIndex":2,"filterCriteria":{"condition":{"type":"NUMBER_GREATER","values":[{"userEnteredValue":"100"}]}}}].; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc sheets filters update <id> <spreadsheet-id> --criteria <value>--range
(required) A1 range with a sheet name (Sheet1!A2:A) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets filters update <id> <spreadsheet-id> --range <value>--replace
Replace an existing filter on the tab.
Type: string. Optional.
orc sheets filters update <id> <spreadsheet-id> --replace <value>filters delete
Clear the basic filter
orc sheets filters delete <id> <spreadsheet-id> [options]Unique options
--tab
(required) Tab title or numeric sheet ID.; max 100 chars
Type: string. Optional.
orc sheets filters delete <id> <spreadsheet-id> --tab <value>bandings list
List alternating colors
orc sheets bandings list <id> <spreadsheet-id> [options]Unique options
--tab
Only this tab (title or sheet ID).; max 100 chars
Type: string. Optional.
orc sheets bandings list <id> <spreadsheet-id> --tab <value>bandings create
Add alternating colors
orc sheets bandings create <id> <spreadsheet-id> [options]Unique options
--column-properties
Body field: column_properties; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets bandings create <id> <spreadsheet-id> --column-properties <value>--range
(required) A1 range with a sheet name (Sheet1!A2:A) or a named range name.; max 500 chars
Type: string. Optional.
orc sheets bandings create <id> <spreadsheet-id> --range <value>--row-properties
Sheets BandingProperties for row colors. Defaults to light blue header and alternating rows.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets bandings create <id> <spreadsheet-id> --row-properties <value>bandings delete
Remove alternating colors
orc sheets bandings delete <id> <spreadsheet-id> [options]Unique options
--banded-range-id
Body field: banded_range_id
Type: number. Optional.
orc sheets bandings delete <id> <spreadsheet-id> --banded-range-id <value>--tab
Remove all banding on this tab.; max 100 chars
Type: string. Optional.
orc sheets bandings delete <id> <spreadsheet-id> --tab <value>charts list
List charts
orc sheets charts list <id> <spreadsheet-id> [options]charts create
Create a chart
orc sheets charts create <id> <spreadsheet-id> [options]Unique options
--anchor
Top-left cell, e.g. E2.
Type: string. Optional.
orc sheets charts create <id> <spreadsheet-id> --anchor <value>--height
Body field: height
Type: number. Optional.
orc sheets charts create <id> <spreadsheet-id> --height <value>--spec
(required) Sheets ChartSpec, or an EmbeddedChart with spec and position. Run orc sheets schemas get ChartSpec.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets charts create <id> <spreadsheet-id> --spec <value>--tab
Tab to place the chart on. Without tab and anchor, the spec position (or a new tab) is used.; max 100 chars
Type: string. Optional.
orc sheets charts create <id> <spreadsheet-id> --tab <value>--width
Body field: width
Type: number. Optional.
orc sheets charts create <id> <spreadsheet-id> --width <value>charts update
Update a chart
orc sheets charts update <id> <spreadsheet-id> <chart-id> [options]Unique options
--spec
(required) Replacement ChartSpec (or an EmbeddedChart wrapping one).; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets charts update <id> <spreadsheet-id> <chart-id> --spec <value>charts delete
Delete a chart
orc sheets charts delete <id> <spreadsheet-id> <chart-id> [options]tables update
Rename or resize a Table
orc sheets tables update <id> <spreadsheet-id> <table-id> [options]Unique options
--name
Body field: name; max 200 chars
Type: string. Optional.
orc sheets tables update <id> <spreadsheet-id> <table-id> --name <value>--range
New A1 range including the header row.; max 500 chars
Type: string. Optional.
orc sheets tables update <id> <spreadsheet-id> <table-id> --range <value>tables delete
Delete a Table and its cells
orc sheets tables delete <id> <spreadsheet-id> <table-id> [options]Unique options
--discard-data
Must be true: deleting a table also deletes every cell in its range.; enum: true|false
Type: string. Optional.
orc sheets tables delete <id> <spreadsheet-id> <table-id> --discard-data <value>links list
List cell links
orc sheets links list <id> <spreadsheet-id> [options]Unique options
--range
A1 range with a sheet name (Sheet1!A1:D20) or a named range name.; max 500 chars
Type: string. Required.
orc sheets links list <id> <spreadsheet-id> --range <value>links update
Set cell links
orc sheets links update <id> <spreadsheet-id> [options]Unique options
--cells
(required) Body field: cells; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc sheets links update <id> <spreadsheet-id> --cells <value>notes list
List cell notes
orc sheets notes list <id> <spreadsheet-id> [options]Unique options
--range
A1 range with a sheet name (Sheet1!A1:D20) or a named range name.; max 500 chars
Type: string. Required.
orc sheets notes list <id> <spreadsheet-id> --range <value>notes update
Set or clear cell notes
orc sheets notes update <id> <spreadsheet-id> [options]Unique options
--note
(required) Note text; an empty string clears notes.; max 50000 chars
Type: string. Optional.
orc sheets notes update <id> <spreadsheet-id> --note <value>--range
(required) Cell or range with a sheet name, or a named range name.; max 500 chars
Type: string. Optional.
orc sheets notes update <id> <spreadsheet-id> --range <value>files list
List and search spreadsheets
orc sheets files list <id> [options]Unique options
--query
Only spreadsheets whose name contains this text.; max 200 chars
Type: string. Optional.
orc sheets files list <id> --query <value>exports get
Export to XLSX, PDF, CSV, and more
orc sheets exports get <export-id> [options]copies create
Copy a whole spreadsheet
orc sheets copies create <id> <spreadsheet-id> [options]Unique options
--name
Name of the copy. Defaults to "Copy of …".; max 500 chars
Type: string. Optional.
orc sheets copies create <id> <spreadsheet-id> --name <value>--parent-folder-id
Drive folder for the copy. Defaults to the source folder.
Type: string. Optional.
orc sheets copies create <id> <spreadsheet-id> --parent-folder-id <value>api get
Call a read-only Sheets API method
orc sheets api get <id> [options]Unique options
--body
Request body for methods that take one, in the Discovery request schema.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets api get <id> --body <value>--method
(required) Read-only Discovery method id, for example spreadsheets.values.batchGet.; enum: spreadsheets.developerMetadata.get|spreadsheets.developerMetadata.search|spreadsheets.get|spreadsheets.getByDataFilter|spreadsheets.values.batchGet|spreadsheets.values.batchGetByDataFilter|spreadsheets.values.get
Type: string. Optional.
orc sheets api get <id> --method <value>--params
Path and query parameters by Discovery name, for example {"spreadsheetId":"…","ranges":["A1:B2"]}. Run orc sheets schemas get <method> for the list.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets api get <id> --params <value>api update
Call a mutating Sheets API method
orc sheets api update <id> [options]Unique options
--body
Request body for methods that take one, in the Discovery request schema.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets api update <id> --body <value>--method
(required) Mutating Discovery method id, for example spreadsheets.values.append.; enum: spreadsheets.batchUpdate|spreadsheets.create|spreadsheets.sheets.copyTo|spreadsheets.values.append|spreadsheets.values.batchClear|spreadsheets.values.batchClearByDataFilter|spreadsheets.values.batchUpdate|spreadsheets.values.batchUpdateByDataFilter|spreadsheets.values.clear|spreadsheets.values.update
Type: string. Optional.
orc sheets api update <id> --method <value>--params
Path and query parameters by Discovery name, for example {"spreadsheetId":"…","ranges":["A1:B2"]}. Run orc sheets schemas get <method> for the list.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc sheets api update <id> --params <value>batch-requests create
Apply batchUpdate requests
orc sheets batch-requests create <id> <spreadsheet-id> [options]Unique options
--include-spreadsheet-in-response
Body field: include_spreadsheet_in_response
Type: string. Optional.
orc sheets batch-requests create <id> <spreadsheet-id> --include-spreadsheet-in-response <value>--requests
(required) batchUpdate requests, each an object with exactly one request type key such as {"addChart":{…}}. Run orc sheets schemas list for the types.; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc sheets batch-requests create <id> <spreadsheet-id> --requests <value>--response-include-grid-data
Body field: response_include_grid_data
Type: string. Optional.
orc sheets batch-requests create <id> <spreadsheet-id> --response-include-grid-data <value>--response-ranges
Body field: response_ranges; csv
Type: string. Optional.
orc sheets batch-requests create <id> <spreadsheet-id> --response-ranges <value>schemas list
List methods and request types
orc sheets schemas list [options]schemas get
Get a method, request type, or schema
orc sheets schemas get <name> [options]Examples
Set and clear a Space sheet view
orc sheets tabs update sht_SHEET_ID TAB_ID --sort-column Name --sort-direction asc --filter-column Name --filter-value Task --workspace YOUR_WORKSPACE_ID --format json
orc sheets tabs update sht_SHEET_ID TAB_ID --clear-sort --clear-filter --workspace YOUR_WORKSPACE_ID --format jsonSet and clear a Space sheet view
Read and write in-house sheet rows
echo '{"values":{"COLUMN_ID":"Task"}}' | orc sheets rows create sht_SHEET_ID TAB_ID --stdin --preview --workspace YOUR_WORKSPACE_ID --format json
echo '{"values":{"COLUMN_ID":"Task"}}' | orc sheets rows create sht_SHEET_ID TAB_ID --stdin --workspace YOUR_WORKSPACE_ID --format json
orc sheets rows list sht_SHEET_ID TAB_ID --as csv --max-rows 10 --sample head_and_tail --wrap-untrusted --readonly --workspace YOUR_WORKSPACE_ID --format json
echo '{"values":{"COLUMN_ID":null}}' | orc sheets rows update sht_SHEET_ID TAB_ID ROW_ID --stdin --preview --workspace YOUR_WORKSPACE_ID --format json
orc sheets rows delete sht_SHEET_ID TAB_ID ROW_ID --yes --workspace YOUR_WORKSPACE_ID --format jsonRead and write in-house sheet rows
Manage typed Space sheet columns
orc sheets columns create sht_SHEET_ID TAB_ID --title Price --type currency --currency-code JPY --workspace YOUR_WORKSPACE_ID --format json
orc sheets columns list sht_SHEET_ID TAB_ID --workspace YOUR_WORKSPACE_ID --format json
orc sheets columns update sht_SHEET_ID TAB_ID COLUMN_ID --title Amount --position 0 --pinned true --hidden false --workspace YOUR_WORKSPACE_ID --format json
orc sheets columns delete sht_SHEET_ID TAB_ID COLUMN_ID --yes --workspace YOUR_WORKSPACE_ID --format jsonManage typed Space sheet columns
Manage Space sheet tabs
orc sheets tabs create sht_SHEET_ID --title Tasks --workspace YOUR_WORKSPACE_ID --format json
orc sheets tabs update sht_SHEET_ID TAB_ID --title Backlog --index 0 --hidden true --workspace YOUR_WORKSPACE_ID --format json
orc sheets tabs update sht_SHEET_ID TAB_ID --hidden false --workspace YOUR_WORKSPACE_ID --format json
orc sheets tabs delete sht_SHEET_ID TAB_ID --yes --workspace YOUR_WORKSPACE_ID --format json
orc sheets tabs update sht_SHEET_ID TAB_ID --deleted false --workspace YOUR_WORKSPACE_ID --format jsonManage Space sheet tabs
Create and list Space sheets
orc sheets create --title Plan --workspace YOUR_WORKSPACE_ID --format json
orc sheets list --workspace YOUR_WORKSPACE_ID --format jsonCreate and list Space sheets
Read, update, and delete a Space sheet
orc sheets get sht_SHEET_ID --workspace YOUR_WORKSPACE_ID --format json
orc sheets update sht_SHEET_ID --title Plan --pinned true --sort-position 0 --archived false --updated-at LAST_UPDATED_AT --workspace YOUR_WORKSPACE_ID --format json
orc sheets delete sht_SHEET_ID --updated-at LAST_UPDATED_AT --yes --workspace YOUR_WORKSPACE_ID --format jsonRead, update, and delete a Space sheet
Read a Google spreadsheet
orc sheets get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --format jsonRead a Google spreadsheet
Inspect the structure
orc sheets get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --format jsonInspect 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).
orc sheets values get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < read.jsonRead ranges and Table columns
{
"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.
orc sheets values update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < write.jsonPreview a change, then write it
{
"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.
orc sheets tables create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < table.jsonCreate a typed Table
{
"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.
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 jsonAppend rows to a Table
Set up tabs
orc sheets tabs create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --title Weekly --format json
orc sheets tabs update YOUR_CONNECTION_ID SPREADSHEET_ID Weekly --workspace YOUR_WORKSPACE_ID --frozen-rows 1 --index 0 --format json
orc sheets tabs copies create YOUR_CONNECTION_ID SPREADSHEET_ID Weekly --workspace YOUR_WORKSPACE_ID --title 'Weekly (Oct)' --format jsonSet up tabs
Work with rows and columns
resized_tables in the delete result lists native Tables shrunk in the same batch.
orc sheets dimensions create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --tab Weekly --dimension rows --start 2 --count 3 --format json
orc sheets dimensions delete YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --tab Weekly --dimension rows --start 2 --end 4 --format json
orc sheets dimensions update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --tab Weekly --dimension columns --start 1 --end 5 --auto-resize true --format jsonWork with rows and columns
Append rows after a range and clear ranges
Use tables rows create for native Tables.
echo '{"range":"Log!A:C","values":[["2026-10-06","organic",1350]]}' | orc sheets values create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json
orc sheets values delete YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --ranges 'Log!A2:C100' --format jsonAppend rows after a range and clear ranges
Format and merge
--cell-format takes a Sheets API CellFormat; inspect it with orc sheets schemas get CellFormat.
orc sheets formats update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --range 'Weekly!A1:F1' --cell-format '{"textFormat":{"bold":true}}' --format json
orc sheets formats update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --range 'Weekly!C2:C' --number-format '{"type":"currency","pattern":"$#,##0"}' --format json
orc sheets merges create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --range 'Weekly!A1:F1' --format jsonFormat and merge
Fill formulas down, sort, and replace
Exclude the header row from the sort range. The replace result reports how many occurrences changed.
orc sheets ranges copies create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --source 'Weekly!E2:E2' --destination 'Weekly!E3:E200' --paste-type formula --format json
echo '{"range":"Weekly!A2:F200","sort":[{"column":"C","order":"desc"}]}' | orc sheets ranges sorts create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json
orc sheets replacements create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --find Organic --replacement SEO --tab Weekly --format jsonFill formulas down, sort, and replace
Use named ranges
Any command that takes a range also accepts the name.
orc sheets named-ranges create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --name Totals --range 'Weekly!A1:F1' --format json
orc sheets named-ranges list YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --format jsonUse named ranges
Set validation and conditional formats
orc sheets validations update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --range 'Weekly!B2:B' --condition-type ONE_OF_LIST --values organic,paid,referral --format json
echo '{"range":"Weekly!C2:C","type":"number_gt","expression":"1000","cell_format":{"textFormat":{"bold":true}}}' | orc sheets conditional-formats create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format jsonSet validation and conditional formats
Add a filter, banding, and a chart
Charts take a Sheets API ChartSpec and are placed with tab and anchor; inspect the type with orc sheets schemas get ChartSpec.
orc sheets filters update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --range 'Weekly!A1:F200' --format json
orc sheets bandings create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --range 'Weekly!A1:F200' --format json
orc sheets charts create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < chart.jsonAdd a filter, banding, and a chart
{
"tab": "Weekly",
"anchor": "H2",
"spec": {
"title": "Weekly sessions",
"basicChart": {
"chartType": "LINE",
"legendPosition": "BOTTOM_LEGEND",
"domains": [{ "domain": { "sourceRange": { "sources": [{ "sheetId": 0, "startRowIndex": 0, "endRowIndex": 200, "startColumnIndex": 0, "endColumnIndex": 1 }] } } }],
"series": [{ "series": { "sourceRange": { "sources": [{ "sheetId": 0, "startRowIndex": 0, "endRowIndex": 200, "startColumnIndex": 2, "endColumnIndex": 3 }] } } }],
"headerCount": 1
}
}
}Add links and notes
Use runs for several links in one cell. An empty note clears notes.
echo '{"cells":[{"cell":"Weekly!A2","url":"https://example.com/report","text":"Report"},{"cell":"Weekly!B2","runs":[{"text":"Source A","uri":"https://a.example"},{"text":" / "},{"text":"Source B","uri":"https://b.example"}]}]}' | orc sheets links update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json
orc sheets notes update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --range 'Weekly!C2:C50' --note 'Source: GA4, 2026-10-06' --format json
orc sheets links list YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --range 'Weekly!A1:F50' --format jsonAdd links and notes
Read for an agent
--readonly blocks writes before sending; --wrap-untrusted wraps cell values and other external text in untrusted-content markers.
orc sheets get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --include-errors true --readonly --format json
echo '{"tables":[{"table":"Weekly"}],"as":"csv","max_rows":200,"sample":"head_and_tail"}' | orc sheets values get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --readonly --wrap-untrusted --format jsonRead for an agent
Find, export, and copy spreadsheets
exports get returns the file as-is; with --output it saves the file and prints the path and size as JSON.
orc sheets files list YOUR_CONNECTION_ID --workspace YOUR_WORKSPACE_ID --query KPI --format json
orc sheets exports get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --file-format xlsx --output kpi.xlsx
orc sheets copies create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --name 'KPI (2026-10)' --format jsonFind, export, and copy spreadsheets
Call any method directly
Check the parameters with schemas get first. --params holds path and query parameters; --body holds the request body.
orc sheets schemas get spreadsheets.values.batchGet --workspace YOUR_WORKSPACE_ID --format json
orc sheets api get YOUR_CONNECTION_ID --workspace YOUR_WORKSPACE_ID --method spreadsheets.values.batchGet --params '{"spreadsheetId":"SPREADSHEET_ID","ranges":["Metrics!A1:D20"],"valueRenderOption":"FORMULA"}' --format jsonCall any method directly
Apply batchUpdate requests
Google validates every request first and applies all or none. Look up types with orc sheets schemas list and orc sheets schemas get addProtectedRange.
orc sheets batch-requests create YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < requests.jsonApply batchUpdate requests
{
"requests": [
{ "updateSheetProperties": { "properties": { "sheetId": 0, "gridProperties": { "frozenRowCount": 1 } }, "fields": "gridProperties.frozenRowCount" } },
{ "addProtectedRange": { "protectedRange": { "range": { "sheetId": 0, "startRowIndex": 0, "endRowIndex": 1 }, "warningOnly": true } } }
]
}Create a spreadsheet
orc sheets create YOUR_CONNECTION_ID --workspace YOUR_WORKSPACE_ID --title 'AI visibility report' --sheet-titles Summary,Weekly --format jsonCreate a spreadsheet
Permissions
Connect Google Workspace in Settings → Integrations. A read-write connection (the default) requires spreadsheets and documents and optionally requests drive.file. A read-only connection (orc connect-sessions create --provider google-workspace --access-mode read_only) requires spreadsheets.readonly and documents.readonly without Drive access. Both modes optionally request userinfo.email and openid. Drive operations are limited to files used with the app. Existing Google Sheets connections still work. Share the spreadsheet 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.