CLI を使い始める

sheets

orc sheets は、接続した Google アカウントのスプレッドシートを操作します。エージェントが座標を推測しなくて済むように、操作を「構造を知る → 必要な値だけ読む → 変更を確認する → 書き込む」の順で使えるよう設計しています。

get はセル本体を読まずに、タブ、ネイティブテーブル（名前・範囲・列名・列型）、名前付き範囲を返します。values get は複数の A1 範囲とテーブル列を 1 回の Google リクエストで読み、テーブルは名前で指定して必要な列だけを返します。values update は preview を指定すると書き込まずに変更されるセルの前後差分を返します。tables create は型付きのネイティブテーブルを作成し、tables rows create はテーブルの内側（フッターより上）に行を追加します。

書き込みは冪等ではありません。タイムアウトなどで結果が不明な場合は、再送する前に対象範囲を読み直してください。行の追加は upsert ではありません。

使い方

接続 ID を確認します。スプレッドシート ID は URL の /d/ と /edit の間の文字列です。

terminal

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

使用例

サブコマンド

`get`

タブ・テーブル・列型などの構造を取得

terminal

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

`create`

スプレッドシートを作成

terminal

orc sheets create <id> [options]

固有のオプション

`--locale`

Body field: locale; max 20 chars

型: string。任意。

terminal

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

`--sheet-titles`

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

型: string。任意。

terminal

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

`--time-zone`

Body field: time_zone; max 100 chars

型: string。任意。

terminal

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

`--title`

(required) Body field: title; max 500 chars

型: string。任意。

terminal

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

`values get`

複数の範囲とテーブル列の値を取得

terminal

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

固有のオプション

`--max-rows`

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

型: number。任意。

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

型: string。任意。

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

型: string。任意。

terminal

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

`--tables`

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

型: string。任意。

terminal

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

`values update`

複数の範囲に値を書き込む（preview で差分確認）

terminal

orc sheets values update <id> <spreadsheet-id> [options]

固有のオプション

`--data`

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

型: string。任意。

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

型: string。任意。

terminal

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

`--preview`

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

型: string。任意。

terminal

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

`tables create`

型付きのネイティブテーブルを作成

terminal

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

固有のオプション

`--anchor`

Top-left cell of the header row.

型: string。任意。

terminal

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

`--columns`

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

型: string。任意。

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

型: string。任意。

terminal

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

`--name`

(required) Body field: name; max 200 chars

型: string。任意。

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

型: string。任意。

terminal

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

`--sheet`

(required) Existing tab title.; max 100 chars

型: string。任意。

terminal

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

`tables rows create`

テーブルに行を追加

terminal

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

固有のオプション

`--input`

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

型: string。任意。

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

型: string。任意。

terminal

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

使用例

構造を確認する

terminal

orc sheets get YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --format json

構造を確認する

範囲とテーブル列を読む

以下の JSON を read.json に保存します。render は unformatted（正確な数値）、formatted（表示値）、formula（数式）から選べます。

terminal

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

範囲とテーブル列を読む

read.json

{
  "ranges": ["Metrics!A1:A3"],
  "tables": [{ "table": "Weekly", "columns": ["week", "sessions"] }],
  "render": "unformatted",
  "max_rows": 500
}

変更差分を確認してから書き込む

write.json の preview を true にして差分を確認し、問題がなければ false にして実行します。null はセルを変更せず、空文字はセルを空にします。数式を書く場合は input を user_entered にします。

terminal

orc sheets values update YOUR_CONNECTION_ID SPREADSHEET_ID --workspace YOUR_WORKSPACE_ID --stdin --format json < write.json

変更差分を確認してから書き込む

write.json

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

型付きテーブルを作成する

ヘッダー・行・テーブル化を 1 回の原子的なバッチで実行します。日付は ISO 形式（YYYY-MM-DD）で渡せます。型に合わない値は送信前に拒否します。

terminal

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

型付きテーブルを作成する

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 }]
}

テーブルに行を追加する

テーブルはテーブル ID または名前で指定します。存在しない列名は拒否します。

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

テーブルに行を追加する

新しいスプレッドシートを作成する

terminal

orc sheets create YOUR_CONNECTION_ID --workspace YOUR_WORKSPACE_ID --title 'AI visibility report' --sheet-titles Summary,Weekly --format json

新しいスプレッドシートを作成する

必要な権限

Settings → 連携で Google Sheets を接続し、spreadsheets スコープを許可します。対象のスプレッドシートは、接続した Google アカウントと共有されている必要があります。Orchestor ではログインとアクセス可能な Workspace が必要です。

グローバルオプション

orc sheets では、次のグローバルオプションを使用できます。

各オプションの詳細と使用例は、グローバルオプションを参照してください。

​sheets

​使い方

​サブコマンド

​get

​create

​固有のオプション

​--locale

​--sheet-titles

​--time-zone

​--title

​values get

​固有のオプション

​--max-rows

​--ranges

​--render

​--tables

​values update

​固有のオプション

​--data

​--input

​--preview

​tables create

​固有のオプション

​--anchor

​--columns

​--input

​--name

​--rows

​--sheet

​tables rows create

​固有のオプション

​--input

​--rows

​使用例

​構造を確認する

​範囲とテーブル列を読む

​変更差分を確認してから書き込む

​型付きテーブルを作成する

​テーブルに行を追加する

​新しいスプレッドシートを作成する

​必要な権限

​グローバルオプション

sheets

使い方

サブコマンド

`get`

`create`

固有のオプション

`--locale`

`--sheet-titles`

`--time-zone`

`--title`

`values get`

固有のオプション

`--max-rows`

`--ranges`

`--render`

`--tables`

`values update`

固有のオプション

`--data`

`--input`

`--preview`

`tables create`

固有のオプション

`--anchor`

`--columns`

`--input`

`--name`

`--rows`

`--sheet`

`tables rows create`

固有のオプション

`--input`

`--rows`

使用例

構造を確認する

範囲とテーブル列を読む

変更差分を確認してから書き込む

型付きテーブルを作成する

テーブルに行を追加する

新しいスプレッドシートを作成する

必要な権限

グローバルオプション