lark-sheets

sheets (v3)

CRITICAL — Before starting, you MUST first use the Read tool to read ../lark-shared/SKILL.md, which contains authentication and permission handling

Quick Decision

To find spreadsheet files in the cloud space by title or keyword, first use lark-cli docs +search。
docs +search will directly return SHEET results; do not misinterpret it as only being able to search documents / Wiki.
After the spreadsheet URL / token is known, then proceed to sheets +info、sheets +read、sheets +find and other internal object operations.

Core Concepts

Document Types and Tokens

In the Feishu Open Platform, different document types have different URL formats and Token handling methods. When performing document operations (such as adding comments, downloading files, etc.), you must first obtain the correct file_token。

Document URL Formats and Token Handling

URL Format	Example	Token Type	Handling Method
`/docx/`	`https://example.larksuite.com/docx/doxcnxxxxxxxxx`	`file_token`	The token in the URL path is used directly as `file_token` Use
`/doc/`	`https://example.larksuite.com/doc/doccnxxxxxxxxx`	`file_token`	The token in the URL path is used directly as `file_token` Use
`/wiki/`	`https://example.larksuite.com/wiki/wikcnxxxxxxxxx`	`wiki_token`	⚠️ Cannot be used directly; you need to query first to obtain the real `obj_token`
`/sheets/`	`https://example.larksuite.com/sheets/shtcnxxxxxxxxx`	`file_token`	The token in the URL path is used directly as `file_token` Use
`/drive/folder/`	`https://example.larksuite.com/drive/folder/fldcnxxxx`	`folder_token`	The token in the URL path is used as the folder token

Special Handling for Wiki Links (Critical!)

A knowledge base link (/wiki/TOKEN) may contain different types of documents behind it, such as cloud documents, spreadsheets, bitables, etc.You cannot directly assume that the token in the URL is the file_token; you must first query the actual type and real token.

Handling Process

Use wiki.spaces.get_node to query node information

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

Extract key information from the returned result
- node.obj_type: document type (docx/doc/sheet/bitable/slides/file/mindnote)
- node.obj_token：the real document token(used for subsequent operations)
- node.title: document title

Based on obj_type , use the corresponding API

obj_type	Description	API Used
`docx`	New cloud document	`drive file.comments.`、`docx.`
`doc`	Legacy cloud document	`drive file.comments.*`
`sheet`	Spreadsheet	`sheets.*`
`bitable`	Bitable	`bitable.*`
`slides`	Slides	`drive.*`
`file`	File	`drive.*`
`mindnote`	Mind Map	`drive.*`

Query Example

# 查询 wiki 节点
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

Example returned result:

{
   "node": {
      "obj_type": "docx",
      "obj_token": "xxxx",
      "title": "标题",
      "node_type": "origin",
      "space_id": "12345678910"
   }
}

Resource Relationships

Wiki Space (知识空间)
└── Wiki Node (知识库节点)
    ├── obj_type: docx (新版文档)
    │   └── obj_token (真实文档 token)
    ├── obj_type: doc (旧版文档)
    │   └── obj_token (真实文档 token)
    ├── obj_type: sheet (电子表格)
    │   └── obj_token (真实文档 token)
    ├── obj_type: bitable (多维表格)
    │   └── obj_token (真实文档 token)
    └── obj_type: file/slides/mindnote
        └── obj_token (真实文档 token)

Drive Folder (云空间文件夹)
└── File (文件/文档)
    └── file_token (直接使用)

Operation process (important):

create — Create filter
- Used to create a filter for the first time
- ⚠️ range must cover all columns to be filtered (e.g., B1:E200)
- If a filter already exists, using create will overwrite the entire filter
update — Update filter
- Used to add/update conditions for specified columns on an existing filter
- Only specify col and condition; range is not needed
delete — Delete filter
get — Get filter status

Multi-column filter example:

Create a dual filter for media name (column B) and sentiment analysis (column E):

# 1. 删除现有筛选（如有）
lark-cli sheets spreadsheet.sheet.filters delete \
  --params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}'

# 2. 创建第一个筛选，range 覆盖所有要筛选的列
lark-cli sheets spreadsheet.sheet.filters create \
  --params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}' \
  --data '{"col":"B","condition":{"expected":["xx"],"filter_type":"multiValue"},"range":"<sheet_id>!B1:E200"}'

# 3. 添加第二个筛选条件
lark-cli sheets spreadsheet.sheet.filters update \
  --params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}' \
  --data '{"col":"E","condition":{"expected":["xx"],"filter_type":"multiValue"}}'

Common errors:

Wrong Filter Value: The filter already exists; you need to delete it first and then create it
Excess Limit: Adding the same column condition repeatedly during update

Shortcuts (prefer using these first)

Shortcut is a high-level wrapper for common operations (lark-cli sheets +<verb> [flags]). For operations that have a Shortcut, prefer using it.

Shortcut	Description
`+info`	View spreadsheet and sheet information
`+read`	Read spreadsheet cell values
`+write`	Write to spreadsheet cells (overwrite mode)
`+write-image`	Write an image into a spreadsheet cell
`+append`	Append rows to a spreadsheet
`+find`	Find cells in a spreadsheet
`+create`	Create a spreadsheet (optional header row and initial data)
`+export`	Export a spreadsheet (async task polling + optional download)
`+merge-cells`	Merge cells in a spreadsheet
`+unmerge-cells`	Unmerge (split) cells in a spreadsheet
`+replace`	Find and replace cell values
`+set-style`	Set cell style for a range
`+batch-set-style`	Batch set cell styles for multiple ranges
`+add-dimension`	Add rows or columns at the end of a sheet
`+insert-dimension`	Insert rows or columns at a specified position
`+update-dimension`	Update row or column properties (visibility, size)
`+move-dimension`	Move rows or columns to a new position
`+delete-dimension`	Delete rows or columns

API Resources

lark-cli schema sheets.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli sheets <resource> <method> [flags] # 调用 API

Important: When using the native API, you must first run schema to view the --data / --params parameter structure; do not guess the field format.

spreadsheets

create — Create spreadsheet
get — Get spreadsheet information
patch — Modify spreadsheet properties

spreadsheet.sheet.filters

create — Create filter
delete — Delete filter
get — Get filter
update — Update filter

spreadsheet.sheets

find — Find cell

Permissions table

Method	Required scope
`spreadsheets.create`	`sheets:spreadsheet:create`
`spreadsheets.get`	`sheets:spreadsheet.meta:read`
`spreadsheets.patch`	`sheets:spreadsheet.meta:write_only`
`spreadsheet.sheet.filters.create`	`sheets:spreadsheet:write_only`
`spreadsheet.sheet.filters.delete`	`sheets:spreadsheet:write_only`
`spreadsheet.sheet.filters.get`	`sheets:spreadsheet:read`
`spreadsheet.sheet.filters.update`	`sheets:spreadsheet:write_only`
`spreadsheet.sheets.find`	`sheets:spreadsheet:read`