feishu-cli-read

Feishu document reading skill

Reads content from Feishu cloud documents, spreadsheets, or knowledge bases, converts it to Markdown format, and then analyzes and displays it. Regular spreadsheets use sheet export --format markdown, and wiki sheet uses wiki export。

Prerequisites

feishu-cli: If not yet installed, please go to riba2534/feishu-cli to get the installation method
Authentication completed (feishu-cli auth login）
App permissions: requires docx:document or docx:document:readonly(regular documents),wiki:wiki:readonly(wiki knowledge base)
Token resolution (common to all read commands)：doc export / wiki export / sheet export and other read-type commands uniformly follow "User first + Tenant fallback"—prioritize the User Token in token.json, and fall back to the App Token if not found. Therefore, when reading others' documents, you only need auth login once, and no longer need to pass --user-access-tokenafterward. See the "User Token priority chain" section below for details.

Core concepts

Markdown as an intermediate state: Local documents and Feishu cloud documents are converted via Markdown format, and intermediate files are stored in the /tmp directory.

Usage

feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assets
feishu-cli wiki export <node_token_or_url> --output /tmp/feishu_wiki.md --download-images --assets-dir /tmp/feishu_assets
feishu-cli sheet export <spreadsheet_token_or_url> --format markdown --output /tmp/feishu_sheet.md

Get document metadata (doc get)

Reads basic document information (document_id, revision_id, title), used to confirm the target before export, or to obtain revision_id as a parameter for subsequent API calls. Also follows "User first + Tenant fallback".

Flag	Default value	Description
`<document_id>`	Required	Document ID or URL (`https://xxx.feishu.cn/docx/<id>`）
`-o, --output`	text	Output format, optional `json`
`--user-access-token`	Empty	Manually override the User Token; if not provided, it is automatically read from `~/.feishu-cli/token.json` read

# 文本摘要
feishu-cli doc get ABC123def456

# JSON 输出（脚本里拿 revision_id / title）
feishu-cli doc get ABC123def456 -o json

# 从 URL 直接读
feishu-cli doc get https://xxx.feishu.cn/docx/ABC123def456

List all document blocks (doc blocks)

doc export When a structured block tree cannot be obtained (for example, to analyze the type of each block, locate a specific block, or check the raw API response), use doc blocks. By default, lists the first page (500 blocks); add --all to automatically paginate through all of them.

Flag	Default value	Description
`<document_id>`	Required	Document ID (URL not accepted; please first `doc get` to get the ID)
`--all`	false	Automatically paginate to get all blocks (covers `--page-size` / `--page-token`）
`--page-size`	500	Number of blocks per page
`--page-token`	Empty	Continuation page token
`--document-revision-id`	-1	Document version (-1 = latest)
`--raw`	false	Output the raw Feishu API JSON (including unresolved fields)
`--user-id-type`	open_id	User ID type (open_id/union_id/user_id)
`-o, --output`	text	Output format, optional `json`(CLI normalized structure)
`--user-access-token`	Empty	Manually override the User Token

# 默认：第一页，文本摘要
feishu-cli doc blocks ABC123def456

# 全量分页 + 归一化 JSON
feishu-cli doc blocks ABC123def456 --all -o json

# 拿 API 原始响应（含未识别块类型的 raw 字段）
feishu-cli doc blocks ABC123def456 --all --raw > /tmp/blocks_raw.json

Wiki knowledge base read types (wiki get / nodes / spaces)

The "three-piece directory structure traversal set" of the knowledge base, used together with wiki export to complete the "find node → read content" chain. All three commands follow "User first + Tenant fallback".

wiki get — query node metadata

Flag	Default value	Description
`<node_token \| url>`	Required	Node Token or wiki URL
`-o, --output`	text	Output format, optional `json`
`--user-access-token`	Empty	Manually override User Token

Return fields:space_id / node_token / obj_token(for document API) / obj_type（docx/sheet/bitable/...） / title / has_child。

wiki nodes — list child nodes of a space or parent node

Flag	Default value	Description
`<space_id>`	Required	Knowledge space ID (obtained from `wiki get` or `wiki spaces` )
`--parent`	Empty	Parent node Token; leave blank = list space root nodes
`--page-size`	50	Number of nodes per page
`-o, --output`	text	Output format, optional `json`
`--user-access-token`	Empty	Manually override User Token

wiki spaces — list all knowledge spaces visible to the current identity

Flag	Default value	Description
`--page-size`	50	Number of spaces per page
`-o, --output`	text	Output format, optional `json`
`--user-access-token`	Empty	Manually override User Token

# 1. 列空间
feishu-cli wiki spaces

# 2. 看某节点信息，记下 space_id
feishu-cli wiki get https://xxx.feishu.cn/wiki/Ad8Iw0oz3iSp4kkIi7QctVhin3e

# 3. 列该节点下子文档
feishu-cli wiki nodes 7012345678901234567 --parent Ad8Iw0oz3iSp4kkIi7QctVhin3e

# 4. 找到目标后用 wiki export 读内容
feishu-cli wiki export <child_node_token> -o /tmp/child.md

Spreadsheet read (sheet read / list-sheets)

sheet export --format markdown is suitable for "full-sheet export reading"; to read cells by exact range, or to first list worksheet metadata, use the following two commands.

sheet list-sheets — list all worksheets of a spreadsheet

Flag	Default value	Description
`<spreadsheet_token>`	Required	Spreadsheet Token or URL
`-o, --output`	text	Output format, optional `json`
`--user-access-token`	Empty	Manually override User Token

Return sheet_id / title / index / hidden status, for use with sheet read 's SheetID!A1:C10 range syntax.

sheet read — read cells in a specified range

Flag	Default value	Description
`<spreadsheet_token>`	Required	Spreadsheet Token or URL
`<range>`	Required	Range, for example `SheetID!A1:C10`、`A1:B2`(with `--sheet-id`）、`Sheet1!A:C` entire column
`--sheet-id`	Empty	Required when range has no SheetID prefix
`--value-render`	Empty	Cell value rendering:`ToString` / `FormattedValue` / `Formula` / `UnformattedValue`
`--datetime-render`	Empty	Date rendering:`FormattedString`(leave blank to return numeric timestamp)
`-o, --output`	text	Output format, optional `json`
`--user-access-token`	Empty	Manually override User Token

# 列出所有工作表
feishu-cli sheet list-sheets shtcnxxxxxx

# 读单个范围（推荐先 list-sheets 拿 sheet_id）
feishu-cli sheet read shtcnxxxxxx "0b12ab!A1:C10"

# 用工作表 ID 简化范围
feishu-cli sheet read shtcnxxxxxx "A1:C10" --sheet-id 0b12ab -o json

# 拿公式而非求值结果
feishu-cli sheet read shtcnxxxxxx "Sheet1!A1:B20" --value-render Formula

Execution flow

Parse arguments
- Determine URL type:
  - /docx/ → regular document, use doc export
  - /wiki/ → knowledge base document, use wiki export
- If it is a Token, determine the type based on the format
Export as Markdown (including image download)

Regular document:
```
feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assets
```
Spreadsheet blocks embedded in documents are automatically expanded to Markdown tables by default, for easy reading and analysis; if you want to keep the <sheet .../> tags for roundtrip, append --expand-sheets=false。

doc export will automatically resolve User Access Token (if logged in); resolution priority (exactly the same as cmd/utils.go::resolveOptionalUserTokenWithFallback + internal/auth/resolve.go::ResolveUserAccessToken implementation):
1. --user-access-token command-line argument (if this token equals an expired access_token in token.json and the refresh_token is still valid, refresh automatically)
2. FEISHU_USER_ACCESS_TOKEN environment variable (also supports automatic refresh via local identity extension)
3. ~/.feishu-cli/token.json(via auth login saved; if access_token is expired, use refresh_token to automatically renew it and write it back)
4. config.yaml in user_access_token(static configuration, will not be refreshed automatically)
5. App Token fallback(the resource API will also accept it, accessing as the tenant identity; when errors such as 1770032/forbidden occur, it indicates that the document is not visible to the App, and you must go through the first 4 steps to obtain a User Token)
When a User Token is found, use the user identity to access; when it is not found or parsing fails, fall back to the App Access Token (tenant identity).

If you encounter code=1770032 forBidden(App has no permission and is not logged in) or code=99991679 Unauthorized(User Token is missing scope), you need to first enable docx:document:readonlyfor the app in the Feishu Open Platform, and then complete User Token authorization:
```
# 第一步：在飞书开放平台 → 你的应用 → 权限管理 → 搜索 docx:document:readonly → 开通
# （或复制 README 的完整权限 JSON 一次性导入）
feishu-cli auth login
```
Knowledge base document:
```
feishu-cli wiki export <node_token> --output /tmp/feishu_wiki.md --download-images --assets-dir /tmp/feishu_assets
```
Regular spreadsheet:
```
feishu-cli sheet export <spreadsheet_token> --format markdown --output /tmp/feishu_sheet.md
```
If --sheet-id is not specified, all visible worksheets will be read; to view only a single worksheet, add --sheet-id <sheet_id>。

Important: be sure to use the --download-images parameter to download images in the document locally; otherwise you can only see feishu://media/<token> references and cannot understand the image content.

Optional parameter：
- --user-access-token: manually specify the User Access Token (if not filled in, it is automatically read from ~/.feishu-cli/token.json )
- --front-matter: add YAML front matter at the top of the Markdown (including title and document ID)
- --highlight: preserve text color and background color (output as HTML <span> tags)
- --expand-mentions: expand @users into a friendly format (enabled by default; requires contact:user.base:readonly permission)
- --expand-sheets: expand embedded spreadsheets in the document into Markdown tables (enabled by default; when set to false , preserve <sheet .../> tags)
Read text content
- Use the Read tool to read the exported Markdown file
- Analyze the document structure and text content
Read and understand image content
- Check whether the directory specified by --assets-dir contains downloaded images
- Use the Read tool to read the image files one by one(Claude supports multimodality and can directly understand image content)
- Integrate the image content into the document analysis
```
# 列出下载的图片
ls /tmp/feishu_assets/

# 使用 Read 工具查看图片
# Read /tmp/feishu_assets/image_1.png
# Read /tmp/feishu_assets/image_2.png
```
Report the results
- Provide a document summary (including descriptions of image content)
- Keep the Markdown file and images for the user to perform further operations

Output format

Report to the user:

Document title
Document structure overview (heading hierarchy)
Content summary (key information)
Image content description (if there are images)
Markdown file path (for subsequent use)
Image file path (if downloaded)

Supported URL formats

URL format	Type	Command
`https://xxx.feishu.cn/docx/<id>`	Regular document	`doc export`
`https://xxx.feishu.cn/sheets/<token>`	Regular spreadsheet	`sheet export --format markdown`
`https://xxx.feishu.cn/wiki/<token>`	Knowledge base (docx/sheet)	`wiki export`
`https://xxx.larkoffice.com/docx/<id>`	Regular document	`doc export`
`https://xxx.larkoffice.com/sheets/<token>`	Regular spreadsheet	`sheet export --format markdown`
`https://xxx.larkoffice.com/wiki/<token>`	Knowledge base (docx/sheet)	`wiki export`

Example

# 读取普通文档
feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assets
feishu-cli doc export https://xxx.feishu.cn/docx/<document_id> --output /tmp/feishu_doc.md

# 读取知识库文档
feishu-cli wiki export <node_token> --output /tmp/feishu_wiki.md --download-images --assets-dir /tmp/feishu_assets
feishu-cli wiki export https://xxx.feishu.cn/wiki/<node_token> --output /tmp/feishu_wiki.md

# 读取普通电子表格为 Markdown
feishu-cli sheet export <spreadsheet_token> --format markdown -o /tmp/feishu_sheet.md

Export format description

The exported Markdown supports conversion of the following Feishu-specific block types:

Feishu block types	Markdown representation
Callout highlight blocks	`> [!NOTE]`、`> [!WARNING]` and 6 other GitHub-style alerts
Block-level/inline formulas	$formula$ (LaTeX format)
Board	`[画板/Whiteboard](feishu://board/...)` link
Spreadsheet block (Sheet)	Expanded to a Markdown table by default; when `--expand-sheets` is disabled, output `<sheet .../>`
ISV block (Mermaid)	Board link
QuoteContainer	`>` quote syntax (supports nesting)
AddOns/SyncedBlock	Transparently expand the content of child blocks
Iframe	`<iframe>` HTML tags

When using the --highlight parameter, colored text is output as <span style="color:..."> tags.

Advanced: Wiki directory node handling

Knowledge base documents may bedirectory nodes(containing child nodes), which require special handling.

1. Identify directory nodes

When exporting a knowledge base document, if the Markdown content appears as:

[Wiki 目录 - 使用 'wiki nodes <space_id> --parent <node_token>' 获取子节点列表]

This indicates that this is aWiki directory node(block_type=42), and the list of child documents is stored in the knowledge base metadata.

2. Get the child node list

# 1. 先获取节点信息，记录 space_id
feishu-cli wiki get <node_token>

# 2. 列出该节点下的子节点
feishu-cli wiki nodes <space_id> --parent <node_token>

3. Complete handling process

# 步骤 1：尝试导出文档
feishu-cli wiki export <node_token> -o /tmp/doc.md

# 步骤 2：检查内容
# 如果显示 "[Wiki 目录...]"，说明是目录节点

# 步骤 3：获取节点信息
feishu-cli wiki get <node_token>
# 记录 space_id 和 has_child 字段

# 步骤 4：获取子节点
feishu-cli wiki nodes <space_id> --parent <node_token>

# 步骤 5：逐个导出子节点
feishu-cli wiki export <child_node_token_1> -o /tmp/child1.md
feishu-cli wiki export <child_node_token_2> -o /tmp/child2.md

Error handling and edge cases

1. Common errors

Error	Cause	Solution
`code=1770032, msg=forBidden`	The App Token does not have permission to access this document	Enable it on the Feishu Open Platform application permission management page `docx:document:readonly`, then `auth login` authorize the User Token
`code=99991679, msg=Unauthorized`	The User Token is missing `docx:document:readonly` scope	Enable it on the Feishu Open Platform application permission management page `docx:document:readonly`, then re- `auth login`
`code=131002, param err`	Parameter error	Check the token format
`code=131001, node not found`	Node does not exist	Check whether the token is correct
`code=131003, no permission`	No permission to access	Confirm that the application has the wiki:wiki:readonly permission
`code=131004, space not found`	Knowledge space does not exist	Check whether space_id is correct
Empty content or `Unknown block type`	special block type	See the "Advanced: Wiki directory node handling" section

2. Edge case handling

Case 1: Document content is empty

Check whether the document is really empty
Check whether you have permission to view the content
Check whether it is a directory node (see above)

Case 2: Image download failed

Check whether the --assets-dir directory is writable
Check the network connection
The image may have been deleted or expired

Case 3: Some block types cannot be recognized

The Feishu API may return unknown block types
These blocks will be displayed as 
This is normal and does not affect the reading of other content

Case 4: Large documents

Documents with more than 1000 blocks may need to be fetched with pagination
Use feishu-cli doc blocks <doc_id> --all to automatically paginate

3. Retry mechanism

If you encounter network errors or API rate limiting:

# 添加 --debug 查看详细错误信息
feishu-cli wiki export <token> --debug

# 等待几秒后重试
sleep 5 && feishu-cli wiki export <token>

Notes

Identify directory nodes: The content of a directory node is a list of child nodes, not the actual document content
Formula content: Exported LaTeX formulas remain as in the original text and can be displayed directly by Markdown renderers
Callout types: Supports six highlight block types: NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS

FAQ

Q: Prompted insufficient permissions / no permission / forBidden

Confirm that the app has obtained docx:document:readonly(regular document) or wiki:wiki:readonly(knowledge base) permissions
If it is someone else's document and the App has not been added as a collaborator, you need to use a User Token:
1. On the Feishu Open Platform → your app → Permission Management → enable docx:document:readonly
2. Run feishu-cli auth login
3. After authorization, doc export will be read automatically, with no additional parameters required

Q: Document does not exist / node not found

Check whether the document ID or node_token is correct (note the distinction between document_id and node_token）
When extracting the ID from the URL, confirm that the correct path segment is used (/docx/ after is document_id,/wiki/ after is node_token)

Q: Token expired / authentication failed

Run feishu-cli auth status to check the current authentication status
If expired, run feishu-cli auth login to re-authenticate
If using an App Access Token, check whether the FEISHU_APP_ID and FEISHU_APP_SECRET environment variables are correct