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/临时性错误