feishu-cli-drive

Feishu Drive Enhanced (Drive)

drive The command group provides enhanced capabilities that coexist with the old file / media / comment add commandcoexistingcapabilities: chunked upload, markdown shortcut export, async task resume, rich text comments, wiki link parsing.

feishu-cli: If not yet installed, please go to riba2534/feishu-cli for installation instructions.

Prerequisites

Authentication：
- Requires User Token（requireUserToken, errors out directly if not logged in):upload/download/export/export-download/import/move/add-comment/task-result/search/apply-permission, first feishu-cli auth login。
- after login, User preferred + App fallback（resolveOptionalUserTokenWithFallback, no error if not logged in):pull/push/status/inspect. Already auth login automatically uses User Token; falls back to App Token if not logged in (note that the Bot usually cannot see private files in your Drive).
Precheck：feishu-cli auth check --scope "drive:file:upload" can verify scope

Command quick reference

0. Metadata / Permission request (new in v1.29+ ⭐)

# 解析任意文档 URL → 输出 type/title/canonical token（自动展开 wiki）
feishu-cli drive inspect --url "https://xxx.feishu.cn/docx/doxcnxxx"
feishu-cli drive inspect --url "https://xxx.feishu.cn/wiki/wikcnxxx"   # 自动 wiki get_node
feishu-cli drive inspect --url doxcnxxx --type docx -o json            # 裸 token + JSON

# 向文档所有者申请权限（埋藏 API，飞书文档站未收录，但 lark-cli 已实现）
# 必需 User Token + docs:permission.member:apply scope（或 drive:drive 等任一大权限）
feishu-cli drive apply-permission --token "<url 或裸 token>" --perm view --remark "申请理由"
feishu-cli drive apply-permission --token doxcnxxx --type docx --perm edit --remark "..."
feishu-cli drive apply-permission --token <url> --perm view --dry-run    # 预览请求

See feishu-cli-toolkit/references/embedded-api-discovery.md(buried API research methodology).

1. Upload / Download

# 上传（>20MB 自动走 3 段式分块 upload_prepare/upload_part/upload_finish）
feishu-cli drive upload --file /tmp/report.pdf
feishu-cli drive upload --file /tmp/big.zip --folder-token fldxxx --name "年度报告.zip"

# 下载（流式 + 路径校验 + --overwrite + --timeout，大文件自动 Range 分片兜底）
feishu-cli drive download --file-token boxcnxxxx --output ./report.pdf
feishu-cli drive download --file-token boxcnxxxx --output ./downloads/ --overwrite
feishu-cli drive download --file-token boxcnxxxx --output ./big.zip --timeout 30m

Key points：

drive upload Chunked upload independently retries each chunk 3 times, using io.SectionReader The outer layer only opens the file once
drive download of --output can be a file path (used directly) or a directory (file name uses file_token itself, not parsed from response headers for now)
drive download When downloading with user identity, if the server returns a large file limit, it will automatically use HTTP Range chunked download and merge
If you need a custom file name, please pass the full path explicitly:--output ./downloads/report.pdf

2. Document export (including markdown shortcut path)

# docx → markdown：走 /docs/v1/content 快捷路径，立即返回（不跑异步 export_tasks）
feishu-cli drive export --token docxxxx --doc-type docx --file-extension markdown --output-dir ./exports

# docx → pdf：走异步 export_tasks，有界轮询 10×5s，超时返回 next_command
feishu-cli drive export --token docxxxx --doc-type docx --file-extension pdf --output-dir ./exports

# sheet → csv 指定 sheet_id
feishu-cli drive export --token sheetxxxx --doc-type sheet --file-extension csv --sub-id sheet_1

# bitable → csv 指定 table_id
feishu-cli drive export --token basexxxx --doc-type bitable --file-extension csv --sub-id tblxxxx

Supported formats：

--doc-type: doc / docx / sheet / bitable
--file-extension: docx / pdf / xlsx / csv / markdown(markdown only supported for docx)

Resume process after timeout：

# drive export 超时会输出：
# next_command: feishu-cli drive task-result --scenario export --ticket abc --file-token xxx

# 1. 轮询任务状态
feishu-cli drive task-result --scenario export --ticket abc --file-token xxx

# 2. 任务完成后下载产物
feishu-cli drive export-download --file-token boxxxx --output-dir ./exports

3. `drive export-download` — download the completed export file

feishu-cli drive export-download --file-token boxxxx --output-dir ./exports
feishu-cli drive export-download --file-token boxxxx --file-name "报告.pdf" --overwrite

4. Document import

# 本地文件 → 云文档（docx / sheet / bitable）
feishu-cli drive import --file report.docx --type docx
feishu-cli drive import --file data.xlsx --type sheet --folder-token fldxxx
feishu-cli drive import --file bigsheet.csv --type bitable --folder-token fldxxx

# 注意：docx/sheet 导入上限 20MB，bitable 上限 100MB

Key technical points：

Uses official /medias/upload_all endpoint（parent_type=ccm_import_open + extra），Does not leave intermediate files in the user's Drive(this is the core difference from the old doc import-file )
Format-specific size limits: docx 20MB / sheet 20MB / bitable 100MB. docx/sheet over 20MB will directly error, and will not automatically bypass the format limit.
Bounded polling 30×2s, returns on timeout next_command

5. Move (automatic folder polling)

# 文件移动（同步，立即返回）
feishu-cli drive move --file-token boxxxx --type docx --folder-token fldxxx

# 文件夹移动（异步，自动轮询 task_check 30×2s）
feishu-cli drive move --file-token fldxxx --type folder --folder-token fldyyy

Key points：

Folder move automatically polls, no longer "fire and forget"
Returns on timeout task_id, can use drive task-result --scenario task_check to continue

6. Rich text comments (most powerful command)

# 全局评论
feishu-cli drive add-comment --doc doccnxxxx --content '[{"type":"text","text":"需要修改标题"}]'

# 通过 docx URL
feishu-cli drive add-comment --doc "https://xxx.feishu.cn/docx/doccnxxxx" \
  --content '[{"type":"text","text":"评论内容"}]'

# 通过 wiki URL（自动解析到真实 docx）
feishu-cli drive add-comment --doc "https://xxx.feishu.cn/wiki/nodxxxx" \
  --content '[{"type":"text","text":"收到"}]'

# 局部评论（锚定到 docx block）
feishu-cli drive add-comment --doc doccnxxxx --block-id blk_xxx \
  --content '[{"type":"text","text":"这段重写"}]'

# 富文本：文本 + 提及用户 + 链接混合
feishu-cli drive add-comment --doc doccnxxxx --content '[
  {"type":"text","text":"请 "},
  {"type":"mention_user","mention_user":"ou_xxx"},
  {"type":"text","text":" 查看 "},
  {"type":"link","link":"https://feishu.cn"}
]'

reply_elements element types：

text — plain text
mention_user — mention user (pass mention_user or text field as open_id)
link — link (pass link or text field as URL)

Document input formats：

docx token (pass directly)
docx URL（https://xxx.feishu.cn/docx/xxx）
doc URL (legacy document)
wiki URL (automatically resolves to the real obj_token + obj_type)

7. Generic async task query

# 查询导入任务
feishu-cli drive task-result --scenario import --ticket abcxxx

# 查询导出任务（需要额外传 file-token 作为原始文档 token）
feishu-cli drive task-result --scenario export --ticket abcxxx --file-token docxxxx

# 查询 folder move 等通用任务
feishu-cli drive task-result --scenario task_check --task-id taskxxx

Three scenarios:import / export / task_check. Used for drive export / drive import / drive move relay completion after timeout.

8. Local ↔ cloud drive one-way mirror (pull/push/status)

One-way mirror between a cloud drive folder and a local directory, including SHA-256 content comparison and --delete-* --yes dual-confirmation safety switch.Only mirror type=file entries, online documents such as docx/sheet/bitable/mindnote/slides/shortcut do not participate (there is no equivalent local binary).

# status：双向 SHA-256 对照，只读，不动文件
feishu-cli drive status --folder-token fldxxx --local-dir ./mirror
# 输出 4 个桶：new_local / new_remote / modified / unchanged

# pull：云盘 → 本地，递归下载
feishu-cli drive pull --folder-token fldxxx --local-dir ./mirror
feishu-cli drive pull --folder-token fldxxx --local-dir ./mirror --if-exists skip
feishu-cli drive pull --folder-token fldxxx --local-dir ./mirror --delete-local --yes

# push：本地 → 云盘，递归上传，自动 create_folder 镜像目录结构
feishu-cli drive push --folder-token fldxxx --local-dir ./mirror              # 默认 --if-exists=skip
feishu-cli drive push --folder-token fldxxx --local-dir ./mirror --if-exists overwrite
feishu-cli drive push --folder-token fldxxx --local-dir ./mirror --delete-remote --yes

Safety semantics：

--local-dir goes through filepath.EvalSymlinks + restricted to within the cwd subtree, preventing symlink escape
--delete-local / --delete-remote must be paired with --yes, if --yes is not passed, execution is directly refused
If there are failures during the upload/download phaseautomatically skip the --delete-* phase, avoiding a half-synced state of "orphans deleted but some files not uploaded successfully"
pull defaults to --if-exists=overwrite(keep local = remote), push defaults to --if-exists=skip(does not touch existing files on the remote, safer)

9. v2 endpoint search (drive search, flat filter)

Goes through the /open-apis/search/v2/doc_wiki/search endpoint, which supports richer flat filters than search docs(v1):

# 关键字 + 类型过滤 + 排序
feishu-cli drive search --query "季度报告" --doc-types DOCX,SHEET --sort edit_time

# 限定在某些云盘文件夹（与 --space-ids 互斥）
feishu-cli drive search --query "API 设计" --folder-tokens fldxxx,fldyyy

# 限定在知识库 space
feishu-cli drive search --query "RFC" --space-ids spcxxx

# 仅匹配标题（避免正文里命中无关结果）
feishu-cli drive search --query "项目周会" --only-title

# 按创建人
feishu-cli drive search --query "复盘" --creator-ids ou_xxx,ou_yyy

# JSON 输出 + 分页
feishu-cli drive search --query "项目" --page-size 20 -o json
feishu-cli drive search --query "项目" --page-token "<上一页 page_token>"

Key points：

--doc-types values are uppercase:DOC / DOCX / SHEET / BITABLE / MINDNOTE / FILE / WIKI / FOLDER / CATALOG / SLIDES / SHORTCUT
--folder-tokens and --space-ids are mutually exclusive (the two scopes doc / wiki)
The title field contains <h>...</h> highlight markers, which the CLI automatically strips
and search docs（v1 /suite/docs-api/search/object) coexist: v1 uses simple owner_ids/chat_ids filtering, v2 uses dual-path refined filtering with doc_filter+wiki_filter

Typical workflows

Workflow A: large file chunked upload + view progress

feishu-cli drive upload --file big_video.mp4 --folder-token fldxxx --name "会议录像.mp4"
# 自动走分块，stderr 输出分片进度
# 上传: 会议录像.mp4 (104857600 bytes)
# 分片上传: 文件大小 100.0 MB, 分片大小 4.0 MB, 共 25 个分片
#   分片 1/25 上传完成 (4.0 MB)
#   ...
# file_token 返回后可直接在飞书里访问

Workflow B: docx batch export to markdown

# 通过 /docs/v1/content 快捷路径，秒出不用等
for doc_id in doc1 doc2 doc3; do
  feishu-cli drive export --token $doc_id --doc-type docx --file-extension markdown --output-dir ./docs
done

Workflow C: export long documents (resume after timeout)

# 1. 触发导出
TICKET=$(feishu-cli drive export --token docxxxxx --doc-type docx --file-extension pdf -o json | jq -r '.ticket // empty')

# 2. 如果超时，输出会带 next_command
#    手动或脚本化接力：
feishu-cli drive task-result --scenario export --ticket $TICKET --file-token docxxxxx

# 3. 任务就绪后下载产物
feishu-cli drive export-download --file-token boxxxx --output-dir ./exports

Workflow D: one-click comment on wiki links

# 不需要先解析 wiki 到 docx，drive add-comment 自动反查
feishu-cli drive add-comment \
  --doc "https://xxx.feishu.cn/wiki/nodxxxxx" \
  --content '[
    {"type":"text","text":"收到，已处理 "},
    {"type":"mention_user","mention_user":"ou_abc123"}
  ]'

Workflow E: import local docx as Feishu documents

# drive import 走临时媒体（不污染云盘）
feishu-cli drive import --file report.docx --type docx --folder-token fldxxx

# 20MB 以上表格文件请导入为 bitable（上限 100MB）
feishu-cli drive import --file big_sheet.xlsx --type bitable --folder-token fldxxx

Workflow F: apply for document permission (apply-permission)

When you encounter "no permission to view this document", you don't need to privately message the document owner on Feishu IM; just apply directly in the terminal:

# 1. 先用 inspect 确认 token 类型（可选；apply-permission 也支持 URL 直接传）
feishu-cli drive inspect --url "https://xxx.feishu.cn/docx/doxcnxxx"
# → 输出 type=docx, title=..., token=doxcnxxx

# 2. 申请只读权限（带申请说明，会出现在发给所有者的审批卡片上）
feishu-cli drive apply-permission \
  --token "https://xxx.feishu.cn/docx/doxcnxxx" \
  --perm view \
  --remark "调研 RFC，需要查看背景设计"

# 3. 申请编辑权限（同一接口，--perm edit）
feishu-cli drive apply-permission --token doxcnxxx --type docx --perm edit --remark "..."

# 4. 预览即将发出的请求（不实际申请）
feishu-cli drive apply-permission --token <url> --perm view --dry-run

⚠️ This is a "buried API" (not listed on the Feishu docs site but already implemented in lark-cli), requires User Token + docs:permission.member:apply scope (or any broad permission such as drive:drive）。

Workflow G: get a URL → parse token / title / type in one command (inspect)

When writing scripts or orchestrating Agents, you often need to look up document metadata from a URL,inspect is the fastest path:

# docx URL → 输出 type=docx + 标题 + 裸 token + canonical URL
feishu-cli drive inspect --url "https://xxx.feishu.cn/docx/doxcnxxx"

# wiki URL → 自动展开到底层文档（自动调 wiki get_node 拆 obj_token + obj_type）
feishu-cli drive inspect --url "https://xxx.feishu.cn/wiki/wikcnxxx"
# → 输出 type=docx, token=<真实 docx token>

# 裸 token + 显式 type → 拿标题做权限/分类
feishu-cli drive inspect --url doxcnxxx --type docx

# JSON 输出（脚本/Agent 友好）
TOKEN=$(feishu-cli drive inspect --url <url> -o json | jq -r '.token')
TITLE=$(feishu-cli drive inspect --url <url> -o json | jq -r '.title')

# 与其他命令串起来：解析 wiki → 导出 markdown
DOC_TOKEN=$(feishu-cli drive inspect --url "https://xxx.feishu.cn/wiki/wikcnxxx" -o json | jq -r '.token')
feishu-cli drive export --token $DOC_TOKEN --doc-type docx --file-extension markdown --output-dir ./out

Differences from other commands:inspect isread-only, does not require User Token(User preferred + App fallback), and even when not logged in you can query metadata of public/Bot-visible documents; after logging in, User Token will be used to see the full permission scope.

Comparison with old commands

Old command	New drive command	Difference
`file upload`	`drive upload`	drive supports User Token + chunking + per-chunk retry
`file download`	`drive download`	drive supports User Token + `--overwrite` + `--timeout` + path validation
`file move`	`drive move`	drive folder move automatically polls task_check
`doc export-file --type pdf`	`drive export --doc-type docx --file-extension pdf`	drive adds markdown shortcut path + sub-id + resume
`doc import-file --type docx`	`drive import --type docx`	drive goes through `/medias/upload_all`(no intermediate files left)
`comment add --type docx`	`drive add-comment --doc <url>`	drive supports rich text + wiki parsing + inline comments

Old commands will not be removed, and can still be used (for simple scenarios with App Token), but new capabilities are only in the drive command group.

Permission requirements

Command	Token strategy	Required scope
`drive upload`	User Token required	`drive:file:upload`
`drive download`	User Token required	`drive:file:download`
`drive export`	User Token required	`docs:document:export`、`drive:drive.metadata:readonly`(exporting markdown also requires `docs:document.content:read`）
`drive export-download`	User Token required	`drive:file:download`
`drive import`	User Token required	`docs:document:import`、`drive:file:upload`
`drive move`	User Token required	`drive:file:write` 1
`drive add-comment`	User Token required	`docs:document.comment:create`、`docs:document.comment:write_only`; wiki URL also requires `wiki:node:read`; docx inline comments also require `docx:document:readonly`
`drive task-result`	User Token required	`drive:drive.metadata:readonly`(specifically depending on the scenario:`import` also requires `docs:document:import`；`export` also requires `docs:document:export`）
`drive pull` / `status`	User preferred + App fallback	`drive:drive.metadata:readonly`、`drive:file:download`
`drive push`	User preferred + App fallback	`drive:drive.metadata:readonly`、`drive:file:upload`、`space:folder:create`; with `--delete-remote` also requires `drive:file:delete`
`drive search`	User Token required	`search:docs:read`
`drive inspect`	User preferred + App fallback (User Token not mandatory)	`drive:drive.metadata:readonly`; wiki URL also requires `wiki:node:read`
`drive apply-permission`	User Token required	`docs:permission.member:apply`(or any of the broader permissions:`drive:drive` / `docs:doc` / `docx:document` , etc.)

Notes

Token strategy：upload/download/export/export-download/import/move/add-comment/task-result/search/apply-permission User Token required;pull/push/status/inspect defaults to User Token after login, and falls back to App Token when not logged in.
SSRF protection: download URLs are validated, rejecting localhost / loopback IPs / private network ranges / link-local
Redirect policy: download HTTP redirects are limited to 5, and HTTPS → HTTP downgrade is prohibited
Large file chunking threshold: fixed at 20MB; larger files are automatically split into chunks
Bounded polling for export: 10 times × 5 seconds (50 seconds total); on timeoutdoes not errorbut returns next_command
Bounded polling for import: 30 times × 2 seconds (60 seconds total); on timeout as above
Folder move polling: 30 times × 2 seconds
Format-specific size limits（import）：docx 20MB / sheet 20MB / bitable 100MB
wiki parsing for add-comment: only supports wiki nodes whose obj_type is docx or doc ; other types (sheet/bitable/mindnote, etc.) will error
Inline comments: only docx supports the --block-id anchor; doc (legacy documents) is not supported
Filename rules：
- drive download：--output uses file_token as the filename when it is a directory (not parsed from response headers); to customize the name, explicitly pass the file path
- minutes download(see feishu-cli-vc): parse from response headers by Content-Disposition > filename* > Content-Type 推导扩展名 > {token}.media priority

Footnotes

drive:file:write is the scope currently declared by the CLI help and code; some Feishu API docs have historically also mentioned space:document:move，The latest Feishu OpenAPI documentation shall prevail. Both cover the same action; new applications should directly request drive:file:write(more general, a general scope for write-type operations). ↩

About this skill

Prerequisites

Command quick reference

0. Metadata / Permission request (new in v1.29+ ⭐)

1. Upload / Download

2. Document export (including markdown shortcut path)

3. drive export-download — download the completed export file

4. Document import

5. Move (automatic folder polling)

6. Rich text comments (most powerful command)

7. Generic async task query

8. Local ↔ cloud drive one-way mirror (pull/push/status)

9. v2 endpoint search (drive search, flat filter)

Typical workflows

Workflow A: large file chunked upload + view progress

Workflow B: docx batch export to markdown

Workflow C: export long documents (resume after timeout)

Workflow D: one-click comment on wiki links

Workflow E: import local docx as Feishu documents

Workflow F: apply for document permission (apply-permission)

Workflow G: get a URL → parse token / title / type in one command (inspect)

Comparison with old commands

Permission requirements

Notes

Footnotes

3. `drive export-download` — download the completed export file