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 decisions

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 being able to search only documents / Wiki.
Once the spreadsheet URL / token is known, 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 or downloading files), 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` usage
`/doc/`	`https://example.larksuite.com/doc/doccnxxxxxxxxx`	`file_token`	The token in the URL path is used directly as `file_token` usage
`/wiki/`	`https://example.larksuite.com/wiki/wikcnxxxxxxxxx`	`wiki_token`	⚠️ Cannot be used directly; you need to query 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` usage
`/drive/folder/`	`https://example.larksuite.com/drive/folder/fldcnxxxx`	`folder_token`	The token in the URL path is used as a folder token

Special handling for Wiki links (critical!)

A knowledge base link (/wiki/TOKEN) may point to different document types such as cloud documents, spreadsheets, or bitables.Do not 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(for subsequent operations)
- node.title: document title

According to obj_type , use the corresponding API

obj_type	Description	API used
`docx`	New cloud document	`drive file.comments.`、`docx.`
`doc`	Old 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 return 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 a filter
- Used to create a filter for the first time
- ⚠️ The range must cover all columns that need filtering (e.g., B1:E200)
- If a filter already exists, using create again will overwrite the entire filter
update — Update a 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: Duplicate addition of the same column condition during update

Shortcuts (recommended to use first)

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

Shortcut	Description
`+info`	View spreadsheet and sheet information
`+read`	Read spreadsheet cell values
`+write`	Write to spreadsheet cells (overwrite mode)
`+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)

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

Permission 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`