feishu-cli-sheet

Feishu spreadsheet advanced capabilities

feishu-cli sheet advanced capabilities of the subcommand group——filter view CRUD + filter condition CRUD + cell dropdown menu CRUD + floating images / write image to cell + batch styles. These were previously mostly capabilities exclusive to lark-cli and have now been filled in to feishu-cli。

scope division: basic read/write (sheet read / write / style / add-rows / add-sheet etc.) and V3 rich text go through the main command feishu-cli sheet / feishu-cli bitable, this skill covers filter-view (including condition) + dropdown + image + batch-set-style. For other subcommands, query feishu-cli sheet --help。

prerequisites

Authentication：sheets:spreadsheet scope; either User Token or App Token is acceptable. Commands default to resolveOptionalUserTokenWithFallback：
- already feishu-cli auth login → automatically use User Token
- not logged in or explicitly --user-access-token left empty → fall back to App Token (Bot identity)
token / sheet-id sources: from the spreadsheet URL https://xxx.feishu.cn/sheets/<token>?sheet=<sheet-id> respectively.

Command quick reference

filter view filter-view (V3 API, 5 commands)

# create —— --name / --filter-view-id 可选，飞书侧自动生成
feishu-cli sheet filter-view create \
  --spreadsheet-token shtcnxxxxxx --sheet-id 0b1212 \
  --range "0b1212!A1:H14" --name "我的视图"

# range 不带 sheetId 前缀时自动补全为 <sheet-id>!<range>
feishu-cli sheet filter-view create --token shtcnxxxxxx --sheet-id 0b1212 --range "A1:H14"

# get —— 取单个视图 id/name/range
feishu-cli sheet filter-view get --token shtcnxxxxxx --sheet-id 0b1212 --filter-view-id pH9hbVcCXA

# update —— --name / --range 至少一个
feishu-cli sheet filter-view update --token shtcnxxxxxx --sheet-id 0b1212 \
  --filter-view-id pH9hbVcCXA --name "新名字"
feishu-cli sheet filter-view update --token shtcnxxxxxx --sheet-id 0b1212 \
  --filter-view-id pH9hbVcCXA --range "0b1212!A1:H20"

# list
feishu-cli sheet filter-view list --token shtcnxxxxxx --sheet-id 0b1212
feishu-cli sheet filter-view list --token shtcnxxxxxx --sheet-id 0b1212 -o json

# delete
feishu-cli sheet filter-view delete --token shtcnxxxxxx --sheet-id 0b1212 --filter-view-id pH9hbVcCXA

filter condition filter-view condition (V3 API, 5 commands)

The CLI now supports writing to filter viewsfilter conditions(located by column letter), no longer only able to create an empty view and then configure it in the Web UI.

# create —— condition-id 为列字母（如 E）；expected 为筛选参数 JSON 数组
feishu-cli sheet filter-view condition create --token shtcnxxxxxx --sheet-id 0b1212 \
  --filter-view-id pH9hbVcCXA --condition-id E --filter-type number --compare-type less --expected '["6"]'

feishu-cli sheet filter-view condition get    --token shtcnxxxxxx --sheet-id 0b1212 \
  --filter-view-id pH9hbVcCXA --condition-id E
feishu-cli sheet filter-view condition update --token shtcnxxxxxx --sheet-id 0b1212 \
  --filter-view-id pH9hbVcCXA --condition-id E --filter-type number --compare-type less --expected '["6"]'
feishu-cli sheet filter-view condition delete --token shtcnxxxxxx --sheet-id 0b1212 \
  --filter-view-id pH9hbVcCXA --condition-id E
feishu-cli sheet filter-view condition list   --token shtcnxxxxxx --sheet-id 0b1212 --filter-view-id pH9hbVcCXA

--filter-type optional hiddenValue / number / text / color；--compare-type such as less / beginsWith / between；--expected is a JSON array (such as '["6"]'）；--condition-id is a column letter (such as E）。

Key parameters：

flag	Required	Description
`--token` / `--spreadsheet-token`	Yes	spreadsheet token (URL `/sheets/<token>`）；`--spreadsheet-token` aligned with the official lark-cli
`--sheet-id`	Yes	worksheet ID (URL `?sheet=<sheet-id>`）
`--range`	required for create	`"<sheetId>!A1:H14"`, without `!` prefix is automatically added
`--name`	No	view name ≤ 100 characters
`--filter-view-id`	create/delete	custom ID on create (10 alphanumeric characters); locates the view on delete
`-o json`	No	output raw JSON
`--user-access-token`	No	explicitly override login state

Underlying call: SDK client.Sheets.SpreadsheetSheetFilterView.{Create, Query, Delete}。

dropdown menu dropdown (V2 dataValidation API, 4 commands)

# set —— 简单选项（CSV 逗号分隔）
feishu-cli sheet dropdown set --token shtcnxxxxxx --range "0b1212!A1:A100" \
  --options "待办,处理中,已完成"

# set —— 多选 + 高亮（colors 数量需与 options 一致，自动开启 highlightValidData）
feishu-cli sheet dropdown set --token shtcnxxxxxx --range "0b1212!B1:B100" \
  --options "P0,P1,P2" --multiple --colors "#FF4D4F,#FAAD14,#52C41A"

# set —— 选项内含逗号 → 必须改用 --options-json（JSON 数组，绕过 CSV 解析）
feishu-cli sheet dropdown set --token shtcnxxxxxx --range "0b1212!C1:C100" \
  --options-json '["a, b","c"]'

# get —— 读取区域的下拉菜单设置（range 必须带 sheetId 前缀）；输出为 JSON（JSON-only，无 text 模式）
feishu-cli sheet dropdown get --token shtcnxxxxxx --range "0b1212!A1:A100"

# update —— 更新下拉（--sheet-id + --ranges 多范围，支持 --multiple / --colors / --highlight）
feishu-cli sheet dropdown update --token shtcnxxxxxx --sheet-id 0b1212 \
  --ranges "0b1212!A1:A100,0b1212!B1:B100" --options "P0,P1,P2" --multiple --colors "#FF4D4F,#FAAD14,#52C41A"

# update —— 仅开启上色高亮（不传 --colors 也能高亮，--highlight 是 update 相对 set 独有的能力）
feishu-cli sheet dropdown update --token shtcnxxxxxx --sheet-id 0b1212 \
  --ranges "0b1212!A1:A100" --options "P0,P1,P2" --highlight

# delete —— 删除下拉（--ranges 逗号分隔，每个带前缀，最多 100 个）
feishu-cli sheet dropdown delete --token shtcnxxxxxx --ranges "0b1212!A1:A100,0b1212!B1:B100"

set uses --range(single),update/delete uses --ranges(multiple ranges separated by commas,update also requires --sheet-id）。 get/update/delete all accept --spreadsheet-token as --token lark-cli-compatible alias (set only --token）。 update exclusive --highlight: only enables option color highlighting (highlightValidData=true), when passing --colors automatically enabled;get only outputs JSON (no text mode).

floating image image (7 commands)

# media-upload —— 上传本地图片素材，返回 file_token（再用于 image add）
feishu-cli sheet image media-upload shtcnxxxxxx ./logo.png
feishu-cli sheet image media-upload shtcnxxxxxx ./logo.png --name banner.png -o json

# write-image —— 把本地图片直接写入单元格（值类型为图片，非浮动图片；起止单元格须相同）
feishu-cli sheet image write-image shtcnxxxxxx 0b1212 --range "0b1212!A1" --image ./logo.png

# get —— 获取单个浮动图片
feishu-cli sheet image get shtcnxxxxxx 0b1212 ScDmuyHm

# update —— 更新浮动图片锚点 / 尺寸 / 偏移（仅更新显式传入的字段）
feishu-cli sheet image update shtcnxxxxxx 0b1212 ScDmuyHm --width 200 --height 150
feishu-cli sheet image update shtcnxxxxxx 0b1212 ScDmuyHm --range "0b1212!B2:B2" --offset-x 5

# 原有：add / list / delete
feishu-cli sheet image list shtcnxxxxxx 0b1212

floating image (float image, draggable and overlaid on cells) ≠ write image to cell (write-image, image as cell value).media-upload 's parent_type is fixed to sheet_image, the target range start and end cells of write-image must be the same.

Batch styles batch-set-style (1 command)

# --data 为 {ranges, style} 对象的 JSON 数组，每个 range 须带 sheetId 前缀
feishu-cli sheet batch-set-style shtcnxxxxxx \
  --data '[{"ranges":["0b1212!A1:A2"],"style":{"font":{"bold":true},"backColor":"#FF0000"}}]'

# 多个范围块
feishu-cli sheet batch-set-style shtcnxxxxxx \
  --data '[{"ranges":["0b1212!A1:A2"],"style":{"font":{"bold":true}}},{"ranges":["0b1212!B1:B2"],"style":{"backColor":"#00FF00"}}]'

style fields follow Feishu V2 styles_batch_update original structure (font / hAlign / vAlign / backColor / foreColor / formatter / clean）。

Key parameters：

Parameter	Required	Description
`<spreadsheet_token>`	Yes	Positional parameter, spreadsheet token (URL `/sheets/<token>`）
`--data`	Yes	`{ranges, style}` JSON array of objects; each `range` must have a sheetId prefix(e.g. `0b1212!A1:C3`）
`--user-access-token`	No	Explicitly override the login state (used when accessing a spreadsheet without App permission)

style follows Feishu V2 styles_batch_update original structure:font(including bold / italic / fontSize / clean）/ hAlign / vAlign / backColor / foreColor / borderType / borderColor / formatter / clean。

Underlying call:PUT /open-apis/sheets/v2/spreadsheets/{token}/styles_batch_update（internal/client/sheets.go）。

Typical workflow

1. Add a status dropdown + priority filter view to the task table

TOKEN=shtcnxxxxxx
SHEET=0b1212

# 状态列下拉（A 列）：待办 / 处理中 / 已完成
feishu-cli sheet dropdown set --token $TOKEN --range "$SHEET!A2:A1000" \
  --options "待办,处理中,已完成"

# 优先级列下拉（B 列）+ 颜色高亮
feishu-cli sheet dropdown set --token $TOKEN --range "$SHEET!B2:B1000" \
  --options "P0,P1,P2" --colors "#FF4D4F,#FAAD14,#52C41A"

# 创建"P0 高优"筛选视图 + 写筛选条件（B 列 = P0）
FV=$(feishu-cli sheet filter-view create --token $TOKEN --sheet-id $SHEET \
  --range "$SHEET!A1:H1000" --name "P0 高优" -o json | jq -r '.filter_view_id')
feishu-cli sheet filter-view condition create --token $TOKEN --sheet-id $SHEET \
  --filter-view-id $FV --condition-id B --filter-type text --compare-type equal --expected '["P0"]'

2. Clean up the worksheet filter view

# list → 拿到 ID → 批量 delete
feishu-cli sheet filter-view list --token $TOKEN --sheet-id $SHEET -o json | \
  jq -r '.[].filter_view_id' | \
  xargs -I{} feishu-cli sheet filter-view delete --token $TOKEN --sheet-id $SHEET --filter-view-id {}

Pitfalls

--options / --options-json are mutually exclusive: passing both will report an error --options 和 --options-json 不能同时使用，请选其一; options containing commas must go through --options-json, otherwise they will be split apart by CSV
dropdown option count ≤ 500 items: Feishu V2 dataValidation supports at most 500 list options at a time (see internal/client/sheets.go:2331); exceeding it causes the API to report an error directly; for batch scenarios, split into multiple dropdown columns by business dimension
each dropdown option ≤ 100 characters: a single option over 100 characters will be rejected by the server; if using --options-json to inject long text, be sure to truncate first or switch to a "short code + comment column" pattern
dropdown --range must have the ! prefix: without the prefix it reports an error directly (--range 必须包含 sheetId 前缀), unlike filter-view which fills it in automatically
--colors length must = options length: for example, 3 options require 3 colors; if one is missing it reports an error --colors 长度(X) 必须与选项数(Y) 一致; passing colors automatically enables highlightValidData: true
dropdown uses English commas as separators, not the Chinese "，"：--options The CSV parser only recognizes ASCII ,, and Chinese commas will merge multiple options into one, which is easy to trip over
filter-view conditions can already be written with the CLI: use filter-view condition create/update(located by column letter --condition-id ); complex conditions for Bitable (not Spreadsheet) still go through feishu-cli bitable view view-filter-set
filter-view range vs. cell write limits：filter-view --range only delimits the view scope,does not write data; writes are subject to V3 limits of ≤ 50000 characters per cell / ≤ 5000 cells per batch / 10 ranges (see the main feishu-cli sheet command)
-o json support surface：filter-view(including condition get/list/create/update）、image get/update/media-upload all support -o json(default text）；dropdown get is JSON-only(default and only outputs JSON, no text mode). Only dropdown set/update/delete and image write-image have no -o, and only return a success summary text (the API itself only returns code/msg)

When to switch to the main command

This skill covers filter-view(including condition）+ dropdown + image + batch-set-style。feishu-cli sheet all other subcommands under it go through the main command and are not within the scope of this skill:

Requirement grouping	Which to use (main command `feishu-cli sheet <cmd>`）
Create / metadata	`create` / `get` / `meta` / `list-sheets`
Read (plain + rich text)	`read` / `read-plain` / `read-rich`
Write / append / insert / clear	`write` / `write-rich` / `append` / `append-rich` / `insert` / `clear`
Write with per-column dtype type fidelity (dates written as Excel serial numbers + date formatter to become real dates, numbers keep numeric values, text uses @ to prevent misinterpretation)	`table-put`(aligned with the official +table-put, pandas to_json(orient=split) shaped JSON; read side `table-get` pending follow-up)
Row/column management	`add-rows` / `add-cols` / `insert-rows` / `delete-rows` / `delete-cols`
Worksheet management	`add-sheet` / `copy-sheet` / `delete-sheet`
Single-range styling / merge / protection	`style` / `merge` / `unmerge` / `protect` / `unprotect`(multi-range batch styling goes through this skill `batch-set-style`）
Find / replace / simple filtering	`find` / `replace` / `filter`(note: different from `filter-view` ,`filter` is temporary filtering)
Export / Markdown import	`export`（XLSX/CSV/MD）/ `import-md`(reference `feishu-cli-toolkit`）
Floating images add/list/delete	`image add` / `image list` / `image delete`(get/update/media-upload/write-image see this skill)
View filtering/sorting/grouping for multi-dimensional tables	`feishu-cli bitable view view-*-set`(stronger semantics, supports conditions)

Quick reference:feishu-cli sheet --help subcommands are subject to --help actual testing; this skill handles filter-view(including condition）/ dropdown / image / batch-set-style, the rest are delegated to the main command.

Permission requirements

sheets:spreadsheet(both read and write are covered; either User Token or App Token works)

Underlying implementation location

Command	CLI entry
`filter-view create/list/delete`	`cmd/sheet_filter_view.go`
`filter-view get/update` + `filter-view condition *`	`cmd/sheet_filter_view_ext.go` / `cmd/sheet_filter_view_condition.go`
`dropdown set`	`cmd/sheet_dropdown.go`
`dropdown get/update/delete`	`cmd/sheet_dropdown_ext.go`
`image add/list/delete`	`cmd/sheet_image.go`
`image get/update/media-upload/write-image`	`cmd/sheet_float_image_ext.go`
`batch-set-style`	`cmd/sheet_style_batch.go`

filter-view goes through the SDK larksheets.SpreadsheetSheetFilterView; dropdown / batch-set-style go through general HTTP direct calls to V2 endpoints (not wrapped by the SDK).