feishu-cli-write

Feishu document writing

This skill is responsible for creating and editing Feishu docx. Importing a Markdown file to create a document can also be done directly with feishu-cli-import; for read-only/export use feishu-cli-read / feishu-cli-export。

Create a new document

feishu-cli doc create --title "文档标题" --output json

After creation, if it needs to be delivered to the user, first resolve the owner:

Prefer reading FEISHU_OWNER_EMAIL, then read ~/.feishu-cli/config.yaml from owner_email。

After resolving the owner, grant full_access：

feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id <owner_email> --perm full_access --notification

Only when FEISHU_TRANSFER_OWNERSHIP=true or configure transfer_ownership: true to transfer ownership:

feishu-cli perm transfer-owner <document_id> --doc-type docx --member-type email --member-id <owner_email> --notification

When no owner is configured, do not use a placeholder email; prompt the user to set FEISHU_OWNER_EMAIL。

Create a document with Markdown

feishu-cli doc import /tmp/doc.md --title "标题" --upload-images

After writing the temporary Markdown, first perform an encoding check:

python3 -c "d=open('/tmp/doc.md','rb').read(); assert b'\xef\xbf\xbd' not in d; d.decode('utf-8')"

doc import Invalid UTF-8 and U+FFFD are already validated within the CLI, but it is still recommended to check first during the generation stage to avoid writing garbled text into cloud documents.

Edit an existing document

Do not treat doc import --document-id as an update command; it converts Markdown into new blocks and appends them to the end of the document. For editing an existing document, prefer doc content-update。

User intent	Recommended mode
Add content at the end	`append`
Completely rewrite the document	`overwrite`
Replace a section	`replace_range`
Find and replace throughout the document	`replace_all`
Insert before/after a section	`insert_before` / `insert_after`
Delete a section	`delete_range`

Common examples:

# 按标题替换章节
feishu-cli doc content-update <document_id> --mode replace_range \
  --selection-by-title "## 旧章节" \
  --markdown-file /tmp/new-section.md

# 在章节后插入
feishu-cli doc content-update <document_id> --mode insert_after \
  --selection-by-title "## 目标章节" \
  --markdown "## 新增章节\n\n内容"

# 追加到末尾
feishu-cli doc content-update <document_id> --mode append \
  --markdown-file /tmp/append.md

# 完全覆盖
feishu-cli doc content-update <document_id> --mode overwrite \
  --markdown-file /tmp/full.md

# 控制 Markdown 表格列宽（默认按内容启发式自动计算）
feishu-cli doc content-update <document_id> --mode append \
  --markdown-file /tmp/with-table.md \
  --table-column-width 80,200,*,120

Key rule: when the user says "modify/replace/update a certain passage", use replace_range or replace_all, do not append, which would cause duplication.

--table-column-width(common to content-update / add, default auto）：auto content-based heuristic | fixed fixed width | N1,N2,... pixel list (* means that column uses auto). Only effective for Markdown content type; you can also write a comment above the table  to override (comments take precedence over flags).

Markdown images

doc import uploads images by default;doc add / content-update use --upload-images to upload local/network images in Markdown and backfill the Image Block.

feishu-cli doc content-update <document_id> --mode append \
  --markdown-file /tmp/with-image.md \
  --upload-images

To insert an image or file separately, use doc media-insert：

feishu-cli doc media-insert <document_id> --file /path/to/image.png --type image --align center --caption "说明"
feishu-cli doc media-insert <document_id> --file /path/to/report.pdf --type file

Low-level block operations

# doc add：默认 --content-type json；--source-type file/content；可指定父块和插入位置
feishu-cli doc add <document_id> content.md --content-type markdown --upload-images
feishu-cli doc add <document_id> --content '[{"block_type":2,...}]' --source-type content
feishu-cli doc add <document_id> doc.md --content-type markdown --block-id <parent_block_id> --index 0
# 带表格的 Markdown 可指定列宽（仅 markdown 内容类型生效）
feishu-cli doc add <document_id> table.md --content-type markdown --table-column-width auto

feishu-cli doc update <document_id> <block_id> --content-file update.json

# doc delete：必须指定父块 ID + 索引范围（左闭右开），或用 --all 删全部子块；--force 跳过确认
feishu-cli doc delete <document_id> <parent_block_id> --start 0 --end 3
feishu-cli doc delete <document_id> <parent_block_id> --all --force

# doc batch-update：默认 --source-type file；可传 --client-token（UUIDv4 幂等）和
# --document-revision-id（乐观锁，默认 -1=最新；指定具体版本时如版本不匹配会失败）
feishu-cli doc batch-update <document_id> updates.json --source-type file
feishu-cli doc batch-update <document_id> updates.json \
  --client-token "$(uuidgen)" \
  --document-revision-id -1

Low-level JSON requires familiarity with the Feishu Block structure; for ordinary section editing, prefer content-update。

`doc add-board` Add a whiteboard block

Insert an empty whiteboard block (block_type=43) into the document, returning block_id and whiteboard_id, which can subsequently be used with feishu-cli board series of commands to operate on the whiteboard content.

flag	Description	Default
`--parent-id`	Parent block ID	Empty (document root node)
`--index`	Insertion position index	-1 (end)
`--output, -o`	Output format (json)	Text

# 末尾添加，JSON 输出便于脚本提取 whiteboard_id
feishu-cli doc add-board <document_id> -o json

# 指定父块和位置
feishu-cli doc add-board <document_id> --parent-id <block_id> --index 0

`doc add-callout` Add a callout block

Insert a Callout highlight block (block_type=19) into the document, and automatically write the text content (the API will automatically generate an empty child block; the CLI has handled it as a direct update rather than an additional creation).

`--callout-type`	Background color	Visual meaning
`info`(default)	Blue (6)	Information notice, lightbulb icon
`warning`	Yellow (4)	Warning notice
`error`	Red (2)	Error notice
`success`	Green (5)	Success notice

Note: The CLI currently exposes only 4 types; for other 6-color Callouts such as CAUTION (orange=3)/IMPORTANT (purple=7), use Markdown <callout type="CAUTION">...</callout> to go through doc import / content-update。

flag	Description	Default
`--callout-type`	Type (info/warning/error/success)	info
`--icon`	Custom icon (emoji shortcode, e.g. `bulb` `fire`）	Empty
`--parent-id`	Parent block ID	Empty (document root node)
`--index`	Insertion position index	-1 (end)
`--output, -o`	Output format (json)	Text

# 默认 info 蓝色
feishu-cli doc add-callout <document_id> "这是一条提示信息"

# 警告 + 自定义图标
feishu-cli doc add-callout <document_id> "请注意" --callout-type warning --icon fire

Table

When importing a Markdown table into docx:

Rows > 9: the CLI creates an initial 9-row table, then uses insert_table_row to append to the same block.
Columns > 9: split by column groups, keeping the first column as the identifier.
When there are extremely many rows (200+), Sheet is more suitable:feishu-cli sheet import-md report.md --title "报表"。

Operations on existing table structures in the document:

feishu-cli doc table insert-row DOC_ID TABLE_BLOCK_ID --index 1 --count 2
feishu-cli doc table delete-rows DOC_ID TABLE_BLOCK_ID --start 1 --end 3
feishu-cli doc table merge-cells DOC_ID TABLE_BLOCK_ID --row-start 0 --row-end 2 --col-start 0 --col-end 3
# 取消合并：指定合并区域内任一单元格的行/列索引
feishu-cli doc table unmerge-cells DOC_ID TABLE_BLOCK_ID --row 0 --col 0

Extended syntax

doc import / content-update Supports common Markdown, as well as HTML extension tags generated by the export side:

<mention-user id="ou_xxx"/>
<mention-doc token="doc_token_xxx" type="docx">标题</mention-doc>
<callout type="NOTE">内容</callout>
<grid cols="2"><column>左</column><column>右</column></grid>

Mermaid / PlantUML will be converted to Feishu whiteboards on import; for syntax limitations, refer to ../feishu-cli-import/references/doc-guide.md。

Verification

After creation/update, confirm that document_id or a success status is returned.
When delivery is needed, confirm that owner permissions have been added.
When there are many images/tables/charts, check the success statistics in the command output.
Before major overwrite operations, first confirm that the user explicitly requests overwrite。