---
title: sheets
description: Google Sheets の構造・値・テーブルを読み書きします。
canonical_url: https://orchestor.io/docs/cli/sheets
markdown_url: https://orchestor.io/docs/cli/sheets.md
contentType: reference
---

# sheets

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

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

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

## 使い方

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

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

*使用例*

## サブコマンド

### `get`

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

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

### `create`

スプレッドシートを作成

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

#### 固有のオプション

##### `--locale`

Body field: locale; max 20 chars

型: `string`。任意。

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

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

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

型: `string`。任意。

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

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

Body field: time_zone; max 100 chars

型: `string`。任意。

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

##### `--title`

(required) Body field: title; max 500 chars

型: `string`。任意。

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

### `values get`

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

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

#### 固有のオプション

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

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

型: `number`。任意。

```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

型: `string`。任意。

```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

型: `string`。任意。

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

型: `string`。任意。

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

### `values update`

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

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

#### 固有のオプション

##### `--data`

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

型: `string`。任意。

```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

型: `string`。任意。

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

型: `string`。任意。

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

### `tables create`

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

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

#### 固有のオプション

##### `--anchor`

Top-left cell of the header row.

型: `string`。任意。

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

型: `string`。任意。

```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

型: `string`。任意。

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

##### `--name`

(required) Body field: name; max 200 chars

型: `string`。任意。

```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

型: `string`。任意。

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

##### `--sheet`

(required) Existing tab title.; max 100 chars

型: `string`。任意。

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

### `tables rows create`

テーブルに行を追加

```bash title="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`。任意。

```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

型: `string`。任意。

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

## 使用例

### 構造を確認する

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

*構造を確認する*

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

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

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

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

```json title="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` にします。

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

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

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

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

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

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

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

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

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

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

```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
```

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

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

```bash title="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` では、次の[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を使用できます。

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%98%E3%83%AB%E3%83%97)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#%E5%87%BA%E5%8A%9B%E5%BD%A2%E5%BC%8F)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#%E5%80%A4%E3%81%A0%E3%81%91%E3%82%92%E5%87%BA%E5%8A%9B)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%B8%E3%81%AE%E5%87%BA%E5%8A%9B)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%9A%E3%83%BC%E3%82%B8%E9%80%81%E3%82%8A)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE%E4%BA%8B%E5%89%8D%E7%A2%BA%E8%AA%8D)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#%E7%A2%BA%E8%AA%8D%E3%81%AE%E7%9C%81%E7%95%A5)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#%E3%81%99%E3%81%B9%E3%81%A6%E3%81%AE%E3%83%9A%E3%83%BC%E3%82%B8%E3%82%92%E5%8F%96%E5%BE%97)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E6%99%82%E9%96%93)

各オプションの詳細と使用例は、[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を参照してください。

---

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