sheets-cli

sheets-cli

Google Sheets の基本操作を行う CLI です。表の読み取り、行の追加、キーまたはインデックスによるセルの更新、一括操作に対応しています。

インストール： sheets-cli はすでにインストールされており、ユーザーの PATH から利用できます。コマンドを直接実行してください。インストールは不要です。

クイックリファレンス

# Find spreadsheet by name
sheets-cli sheets find --name "Projects"

# List sheets/tabs
sheets-cli sheets list --spreadsheet <id-or-url>

# Read table data
sheets-cli read table --spreadsheet <id> --sheet "Sheet1" --limit 100

# Update by key column (preferred - rows can shift)
sheets-cli update key --spreadsheet <id> --sheet "Projects" \
  --key-col "Name" --key "Acme" --set '{"Status":"Done"}'

# Append row
sheets-cli append --spreadsheet <id> --sheet "Projects" \
  --values '{"Name":"NewCo","Status":"Active"}'

ワークフローパターン

読み取り → 判断 → ドライラン → 適用の順に必ず実行してください。

# 1. Understand current state
sheets-cli read table --sheet "Tasks" --limit 100

# 2. Dry-run first
sheets-cli update key --sheet "Tasks" --key-col "ID" --key "TASK-42" \
  --set '{"Status":"Complete"}' --dry-run

# 3. Apply if dry-run looks correct
sheets-cli update key --sheet "Tasks" --key-col "ID" --key "TASK-42" \
  --set '{"Status":"Complete"}'

コマンド

認証（セットアップ）

sheets-cli auth login --credentials <oauth-client.json>
sheets-cli auth status
sheets-cli auth logout

名前でスプレッドシートを検索

sheets-cli sheets find --name "<query>" [--limit 10]

名前に一致するスプレッドシートを Google Drive で検索します。ID、名前、URL を返します。

プロジェクトで Google Drive API が有効になっている必要があります。

シート／タブの一覧表示

sheets-cli sheets list --spreadsheet <id>

シート情報

sheets-cli sheet info --spreadsheet <id> --sheet "<name>"
sheets-cli sheet info --spreadsheet <id> --gid <gid>

名前または GID でシートのメタデータを取得します。

ヘッダー行の取得

sheets-cli header --spreadsheet <id> --sheet "<name>" [--header-row N]

列ヘッダーを返します。指定されていない場合はヘッダー行を自動検出します。

表データの読み取り

sheets-cli read table --spreadsheet <id> --sheet "<name>" [--limit N] [--raw]

{ headers: ["_row", ...], rows: [{_row: N, ...}, ...], headerRow: N } を返します。

各行には _row が含まれます。これは update row で使用する、シート上の絶対行番号です。

範囲の生データを読み取り

sheets-cli read range --spreadsheet <id> --range "Sheet1!A1:B10"

行の追加

sheets-cli append --spreadsheet <id> --sheet "<name>" \
  --values '<json>' [--dry-run]

列名をキーにした JSON オブジェクトを指定します。列の照合では、大文字と小文字を区別せず、空白を正規化します。

キーによる更新（推奨）

sheets-cli update key --spreadsheet <id> --sheet "<name>" \
  --key-col "<column>" --key "<value>" --set '<json>' \
  [--allow-multi] [--dry-run]

key-col が key と一致する行を検索し、--set の列を更新します。複数の行が一致した場合、--allow-multi を指定しないとエラーになります。

行インデックスによる更新

sheets-cli update row --spreadsheet <id> --sheet "<name>" \
  --row <n> --set '<json>' [--dry-run]

1 から始まる行番号で指定した行を更新します。read table の出力にある _row をそのまま使用してください。

行番号

• read table は headerRow と _row フィールドを含む行を返します
• _row はシート上の絶対行番号です。update row --row でそのまま使用してください
• 例：headerRow: 2 は、ヘッダーが 2 行目にあり、最初のデータ行が _row: 3 であることを示します
• 行番号を手作業で計算しないでください。読み取り結果の _row を必ず使用してください

範囲の設定

sheets-cli set range --spreadsheet <id> --range "Sheet1!A1:B2" \
  --values '<2d-json-array>' [--dry-run]

一括操作

sheets-cli batch --spreadsheet <id> --ops '<json-array>' [--dry-run]

操作：append、updateRow、updateKey、setRange。

グローバルオプション

オプション	説明
--spreadsheet <id>	スプレッドシートの ID または完全な URL
--dry-run	適用せずにプレビュー
--header-row <n>	ヘッダー行（省略時は自動検出）
--value-input <mode>	USER_ENTERED（デフォルト）または RAW

出力形式

すべてのコマンドは JSON を返します。

{
  "ok": true,
  "cmd": "update key",
  "spreadsheetId": "...",
  "sheet": "Projects",
  "result": { "matchedRows": 1, "updatedCells": 2 }
}

エラー：

{
  "ok": false,
  "cmd": "update key",
  "error": { "code": "VALIDATION_ERROR", "message": "..." }
}

ベストプラクティス

1. sheets find を使用すると、名前からスプレッドシート ID を取得できます
2. --spreadsheet には URL を指定できます。Google Sheets の完全な URL をそのまま貼り付けてください
3. 行インデックスよりキーによる更新を優先してください。行の挿入や削除で行位置が変わるためです
4. 書き込み前に必ずドライランを実行してください
5. 処理を続ける前に、レスポンスの ok フィールドを確認してください
6. 関連する操作は一括処理にまとめてください。原子性を確保できます
7. 列名の照合では大文字と小文字を区別せず、空白を正規化します
8. ヘッダー行は自動検出されます。空行をスキップし、最初のデータ行を見つけます
9. ヘッダーのないシート： read table は列を A、B、…として返します。--set／--key-col には列記号を使用してください
10. 列記号とヘッダー： ID や URL のようなキーがヘッダー名と列記号のパターンの両方に一致する場合は、ヘッダー名の一致が優先されます。列記号による指定（A、B、AA）は、ヘッダーが一致しない場合の代替としてのみ使用されます
11. 空のシート： append は JSON キーからヘッダー行を書き込んで、シートを初期化できます
12. read table --range には A1:Z を指定できます（シート名が自動的に先頭に付加されます）

終了コード

コード	意味
0	成功
10	検証エラー
20	認証エラー
30	権限エラー
40	API／一時的なエラー