porteden sheets

使用 porteden sheets 执行 Google Sheets 数据操作与文件管理。请使用 -jc 标志 获取 AI 优化的输出格式。

若尚未安装 porteden：运行 brew install porteden/tap/porteden（或 go install github.com/porteden/cli/cmd/porteden@latest）。

初始化配置（仅需一次）

• 浏览器登录（推荐）：porteden auth login — 自动打开浏览器完成授权，凭据安全存储于系统密钥环中
• 直接传入令牌：porteden auth login --token — 令牌将存入系统密钥环
• 验证登录状态：porteden auth status
• 若环境变量中已设置 PE_API_KEY，CLI 将自动使用该密钥（无需额外登录）。
• 访问 Google Drive 需要具备 driveAccessEnabled: true 的令牌，并且关联的 Google 账户必须已授予 Drive 相关权限范围（scopes）。

Sheets 命令（porteden sheets）

数据操作

• 新建空白电子表格：porteden sheets create --name "Q1 Budget"
• 在指定文件夹中新建：porteden sheets create --name "Data" --folder google:0B7_FOLDER
• 使用 CSV 文件初始化内容：porteden sheets create --name "Sales 2026" --csv-file ./sales.csv
• 使用内联 CSV 初始化内容：porteden sheets create --name "Data" --csv "Name,ScorenAlice,95"
• 获取电子表格元信息（含工作表列表、维度等）：porteden sheets info google:SHEETID -jc
• 一次性读取全部工作表（最适合 AI Agent 场景 —— 单次上游调用）：porteden sheets content google:SHEETID -jc
• 读取全部工作表并限制每张表最大行数：porteden sheets content google:SHEETID --max-rows 500 -jc
• 读取指定范围（无单表行数限制）：porteden sheets content google:SHEETID --ranges "Summary!A1:C100,Raw Data!A:Z" -jc
• 读取单元格区域（单个范围）：porteden sheets read google:SHEETID --range "Sheet1!A1:C10" -jc
• 读取整张工作表（单个工作表）：porteden sheets read google:SHEETID --range "Sheet1" -jc
• 写入单元格（JSON 格式）：porteden sheets write google:SHEETID --range "Sheet1!A1:B2" --values '[["Name","Score"],["Alice",95]]'
• 写入单元格（CSV 字符串）：porteden sheets write google:SHEETID --range "Sheet1!A1:B2" --csv "Name,ScorenAlice,95"
• 写入单元格（CSV 文件）：porteden sheets write google:SHEETID --range "Sheet1!A1" --csv-file ./data.csv
• 批量写入多个区域（单次原子调用）：porteden sheets write google:SHEETID --updates '[{"range":"Summary!A1:B1","values":[["Metric","Value"]]},{"range":"Detail!A1","values":[["x"]]}]'
• 追加行（JSON 格式）：porteden sheets append google:SHEETID --range "Sheet1!A:B" --values '[["Bob",87]]'
• 追加行（CSV 格式）：porteden sheets append google:SHEETID --range "Sheet1!A:B" --csv "Bob,87"

工作表（Tab）管理

• 完整读取一张工作表（单次调用，无需指定 A1 范围）：porteden sheets read-tab google:SHEETID --title "Q2 Forecast" -jc
• 按数字 ID 读取工作表：porteden sheets read-tab google:SHEETID --sheet-id 0 -jc
• 新增工作表：porteden sheets add-tab google:SHEETID --title "Q2 Forecast"
• 新增带尺寸/位置参数的工作表：porteden sheets add-tab google:SHEETID --title "Q2 Forecast" --rows 200 --cols 12 --index 2
• 按标题删除工作表：porteden sheets delete-tab google:SHEETID --title "Q2 Forecast" -y
• 按 ID 删除工作表：porteden sheets delete-tab google:SHEETID --sheet-id 1843502915 -y

文件管理

• 复制（即创建副本）电子表格：porteden sheets copy google:SHEETID --name "Q2 Forecast (copy)"

• 复制到指定文件夹：porteden sheets copy google:SHEETID --folder google:0B7_FOLDER

• 获取导出链接（xlsx / pdf / csv）：porteden sheets download google:SHEETID -jc

• 分享给指定用户：porteden sheets share google:SHEETID --type user --role writer --email user@example.com

• 公开分享（任意用户可读）：porteden sheets share google:SHEETID --type anyone --role reader

• 列出当前权限：porteden sheets permissions google:SHEETID -jc

• 重命名：porteden sheets rename google:SHEETID --name "Q2 Budget"

• 删除（移入回收站）：porteden sheets delete google:SHEETID -y

Range 格式说明

• 完整区域：Sheet1!A1:C10
• 整张工作表：Sheet1
• 开放区间（适用于追加场景）：Sheet1!A:B

注意事项

• 登录后凭据将持久化保存在系统密钥环中，后续无需重复认证。
• 设置环境变量 PE_PROFILE=work 可避免反复指定 --profile 参数。
• -jc 是 --json --compact 的简写：去除冗余字段、精简响应结构、降低 token 消耗，专为 AI Agent 设计。
• 所有文件 ID 必须带提供方前缀（例如：google:1BxiMVs0XRA5...），请原样传递。
• 当需要读取多张工作表时，请优先使用 porteden sheets content，而非多次调用 porteden sheets read —— 前者可在单次上游请求中返回全部工作表内容。
• porteden sheets content 默认对每张工作表限制为 200 行 × 26 列。超出此限制的工作表将在响应中标记 clipped: true，并附带一个 fullRange 字符串；可直接将该字符串作为 porteden sheets read --range 的参数进行精确读取。也可通过 --max-rows 5000 提高默认行数上限，或使用 --ranges 显式传入不受限的 A1 表达式。
• porteden sheets create 支持可选参数 --csv 或 --csv-file 用于初始化首张工作表内容；若未指定则创建空白电子表格。这两个参数互斥，不可同时使用。
• 通过 CSV 初始化的电子表格，其首张工作表名称将继承自文件名，而非默认的 Sheet1。 当 Google Drive 导入 CSV 文件时，生成的工作表会采用原始文件名（例如：--name "Q1 Numbers" → 工作表标题为 Q1 Numbers）。下方示例中使用的 Sheet1!... 仅适用于通过 Google Sheets UI 创建的真正空白电子表格。对于 CSV 初始化的电子表格，请先执行 porteden sheets info -jc 查询实际工作表名称，再在 range 中引用，如：'Q1 Numbers'!A1:C10。
• 在 sheets write / sheets append 命令中：--values、--csv 和 --csv-file 三者互斥 —— 请仅提供其中一项。
• 批量写入（sheets write --updates）：接收一个 JSON 数组，每个元素为 {"range","values"} 对象，所有更新将在 单次原子调用 中完成（任一 range 出错将导致整个批次失败，不支持部分写入）。最多支持 50 个 range / 50,000 个单元格。--updates 与 --range/--values/--csv/--csv-file 互斥；但 --raw 仍可全局生效。在需同时填充多个工作表或区域时，应优先选用该方式，而非多次 sheets write 调用。
• sheets read-tab 和 sheets delete-tab 命令必须且只能指定 --title 或 --sheet-id 其中之一。--sheet-id 0 是合法值（首张工作表通常 ID 为 0）。read-tab 返回该工作表的全部已用区域（used range），无需手动指定 A1 范围。add-tab 将返回新工作表的 sheetId；同一电子表格内工作表标题必须唯一。
• sheets copy 将完整复制整个电子表格（非幂等操作 —— 多次调用将生成多个副本），并返回新文件的 ID。该命令本质上是 drive copy 的封装。
• --csv 内联格式：使用 n 作为换行符（例如："Name,ScorenAlice,95nBob,87"）。
• --raw 标志禁用公式解析（写入值将被当作纯文本处理，而非公式）。
• porteden sheets download 仅返回 导出 URL —— 不流式传输二进制内容。
• 响应中的 accessInfo 字段描述了当前令牌的访问限制。
• delete 操作将文件移入回收站（可恢复），可通过 Google Drive 回收站还原文件。
• 执行分享或删除操作前均需确认。
• 支持的环境变量：PE_API_KEY、PE_PROFILE、PE_FORMAT、PE_COLOR、PE_VERBOSE。