lark-drive

drive (v1)

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

Import routing rules: If the user wants to import local Excel / CSV into Base / Bitable / bitable, you must prioritize using lark-cli drive +import --type bitable. Do not switch to lark-base；lark-base first. It is only responsible for in-table operations after the import is complete.

Quick decisions

User wants to import local .xlsx / .csv into Base / Bitable / bitable, the first step must use lark-cli drive +import --type bitable。
User wants to import local .md / .docx / .doc / .txt / .html into an online document, use lark-cli drive +import --type docx。
User wants to import local .xlsx / .xls / .csv into a spreadsheet, use lark-cli drive +import --type sheet。
lark-base is only responsible for Base internal operations after the import is complete (tables, fields, records, views). Do not switch to lark-base。

Core concepts

Document types and tokens

In the Feishu Open Platform, different types of documents 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`	Use the token in the URL path directly as `file_token` Use
`/doc/`	`https://example.larksuite.com/doc/doccnxxxxxxxxx`	`file_token`	Use the token in the URL path 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 actual `obj_token`
`/sheets/`	`https://example.larksuite.com/sheets/shtcnxxxxxxxxx`	`file_token`	Use the token in the URL path directly as `file_token` Use
`/drive/folder/`	`https://example.larksuite.com/drive/folder/fldcnxxxx`	`folder_token`	Use the token in the URL path as the folder token

Special handling for Wiki links (critical!)

Knowledge base links (/wiki/TOKEN) may point to different types of documents, such as cloud documents, spreadsheets, bitables, and more.You cannot directly assume that the token in the URL is a 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：Actual document token(for subsequent operations)
- node.title: document title

According to obj_type , use the corresponding API

obj_type	Description	API used
`docx`	New version cloud document	`drive file.comments.`、`docx.`
`doc`	Old version 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 (直接使用)

Common operation token requirements

Operation	Required token	Description
Read document content	`file_token` / via `docs +fetch` automatic handling	`docs +fetch` Supports passing URL directly
Add local comment (text-selection comment)	`file_token`	When passing `--selection-with-ellipsis` or `--block-id` ,`drive +add-comment` will create a local comment; only supports `docx`, as well as wiki URLs that ultimately resolve to `docx` wiki URL
Add full-text comment	`file_token`	When not passing `--selection-with-ellipsis` / `--block-id` ,`drive +add-comment` creates a full-text comment by default; supports `docx`, legacy `doc` URLs, as well as wiki URLs that ultimately resolve to `doc`/`docx` wiki URL
Download file	`file_token`	Extract directly from the file URL
Upload file	`folder_token` / `wiki_node_token`	Token of the target location
List document comments	`file_token`	Same as adding comments

Comment capability boundaries (critical!)

drive +add-comment supports two modes.
Full-text comment: enabled by default when --selection-with-ellipsis / --block-id is not passed, and can also be explicitly passed as --full-comment; supports docx, legacy doc URLs, as well as wiki URLs that ultimately resolve to doc/docx .
Local comment: enabled when passing --selection-with-ellipsis or --block-id ; only supports docx, as well as wiki URLs that ultimately resolve to docx .
drive +add-comment 's --content requires passing a reply_elements JSON array string, for example --content '[{"type":"text","text":"正文"}]'。
If the wiki does not resolve to doc/docx, do not use +add-comment。
If you need to call the comment V2 protocol more directly at a lower level, then use the native API: first execute lark-cli schema drive.file.comments.create_v2, then execute lark-cli drive file.comments create_v2 .... For full-text comments, omit anchor; for local comments, pass anchor.block_id。

Comment query and statistics criteria (critical!)

When querying document comments, use the drive file.comments list。
drive file.comments list returned by items should be understood as a list of "comment cards"; each item corresponds to one comment card seen in the user interface, rather than a flat list of interaction messages.
Semantically on the server side, when the first comment is created, the first reply in that card is also created at the same time; therefore, what actually carries the body is each item.reply_list.replies, where the first reply is, from the user's perspective, the "comment itself" in this card.
When the user wants to count the "number of comments" or "number of comment cards", just count the length of items ; if it is a full count, then add up the lengths of items returned by pagination for all comments.
When the user wants to count the "number of replies", from the user's perspective the first comment in each comment card should be excluded; the counting criterion is the sum of the lengths of all item.reply_list.replies minus the length of items .
When the user wants to count the "total number of interactions", just count the sum of the lengths of all item.reply_list.replies ; this criterion includes the first comment in each comment card.
If a certain item.has_more=true, it means there are more replies under this comment card that are not included in the current return; in this case, you need to continue calling drive file.comment.replys list to fetch them all, and then perform the full reply count / total interaction count statistics.

Comment business characteristics and guidance (critical!)

Comment sorting guidance

A document usually has multiple comments, and comments are sorted by create_time(creation time).
Important: Only when the user explicitly mentions "latest comment", "last comment", or "earliest comment" is it necessary to sort by create_time :
- All comments must be fetched first (handle pagination to retrieve all data), and you cannot sort after fetching only one page
- "Latest comment" / "Last comment": sort by create_time in descending order and take the first one
- "Earliest comment": sort by create_time in ascending order and take the first one
If the user only says "first comment", directly use drive file.comments list the first one returned; no additional sorting is needed.

Comment reply restrictions

Before adding a comment reply, first check whether the following restrictions exist
Full-text comments do not support replies：is_whole=true comments (full-text comments) cannot have replies added. When encountering such comments, prompt the user that "full-text comments do not support replies".
Resolved comments do not support replies：is_solved=true comments cannot have replies added. When encountering such comments, prompt the user that "this comment has been resolved and cannot be replied to".
Note: When the user wants to reply to a comment but that comment cannot be replied to due to the above restrictions, only prompt that it cannot be replied to;do not automatically find other comments that can be replied to for the user, to avoid not meeting user expectations.

Choosing between batch query and list query

Use drive file.comments batch_query isafter the comment ID is knownfor batch query, and a specific list of comment IDs needs to be passed in.
Use drive file.comments list for paginated retrieval of the comment list, suitable for counting the total number of comments, iterating through all comments, or retrieving scenarios such as "latest/last N comments".

Reaction scenarios

When encountering issues related to reactions on comments / replies (emojis, counts of each emoji, who reacted with what, adding/removing emojis),first read lark-drive-reactions.md to learn how to use it。

Typical errors and solutions

Error message	Cause	Solution
`not exist`	Used the wrong token	Check the token type; wiki links must first be queried to obtain `obj_token`
`permission denied`	No relevant operation permission	Guide the user to check whether the current identity has the corresponding operation permission for the document/file; if needed, the corresponding permission can be granted
`invalid file_type`	file_type parameter error	Pass the correct file_type (docx/doc/sheet) according to `obj_type` Pass the correct file_type (docx/doc/sheet)

Authorize the current app to access the document

When it is necessary to grant document permission tothe current app (bot) itself, first obtain the app's open_id through the bot info interface, then call the permission interface to authorize:

# 1. 获取当前应用的 open_id
lark-cli api GET /open-apis/bot/v3/info --as bot
# 从返回值中取 bot.open_id

# 2. 授权当前应用访问文档
lark-cli drive permission.members create \
  --params '{"token":"<doc_token>","type":"<resource_type>"}' \
  --data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'

Note: This method is only applicable to scenarios where permission needs to be granted tothe current app. When granting permission to other users, directly use their open_id; there is no need to call the bot info interface.

<resource_type> Optional values:doc、docx、sheet、bitable、file、folder、wiki。

Shortcuts (recommended to use first)

Shortcut is a high-level wrapper for common operations (lark-cli drive +<verb> [flags]). Operations with a Shortcut should be used first.

Shortcut	Description
`+upload`	Upload a local file to Drive
`+download`	Download a file from Drive to local
`+add-comment`	Add a full-document comment, or a local comment to selected docx text (also supports wiki URL resolving to doc/docx)
`+export`	Export a doc/docx/sheet/bitable to a local file with limited polling
`+export-download`	Download an exported file by file_token
`+import`	Import a local file to Drive as a cloud document (docx, sheet, bitable)
`+move`	Move a file or folder to another location in Drive
`+delete`	Delete a Drive file or folder with limited polling for folder deletes
`+task_result`	Poll async task result for import, export, move, or delete operations

API Resources

lark-cli schema drive.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli drive <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.

files

copy — Copy file
create_folder — Create folder
list — Get the list under a folder

file.comments

batch_query — Batch get comments
create_v2 — Add full-text/partial (selected text) comment
list — Get document comments with pagination
patch — Resolve/restore comment

file.comment.replys

create — Add reply
delete — Delete reply
list — Get replies
update — Update reply

permission.members

auth —
create — Add collaborator permission
transfer_owner —

metas

batch_query — Get document metadata

user

remove_subscription — Unsubscribe from user- and app-dimension events
subscription — Subscribe to user- and app-dimension events (this release opens the comment-added event)
subscription_status — Query the subscription status of a user or app for a specified event

file.statistics

get — Get file statistics

file.view_records

list — Get the visitor records of a document

file.comment.reply.reactions

update_reaction — Add/delete reaction

Permission table

Method	Required scope
`files.copy`	`docs:document:copy`
`files.create_folder`	`space:folder:create`
`files.list`	`space:document:retrieve`
`file.comments.batch_query`	`docs:document.comment:read`
`file.comments.create_v2`	`docs:document.comment:create`
`file.comments.list`	`docs:document.comment:read`
`file.comments.patch`	`docs:document.comment:update`
`file.comment.replys.create`	`docs:document.comment:create`
`file.comment.replys.delete`	`docs:document.comment:delete`
`file.comment.replys.list`	`docs:document.comment:read`
`file.comment.replys.update`	`docs:document.comment:update`
`permission.members.auth`	`docs:permission.member:auth`
`permission.members.create`	`docs:permission.member:create`
`permission.members.transfer_owner`	`docs:permission.member:transfer`
`metas.batch_query`	`drive:drive.metadata:readonly`
`user.remove_subscription`	`docs:event:subscribe`
`user.subscription`	`docs:event:subscribe`
`user.subscription_status`	`docs:event:subscribe`
`file.statistics.get`	`drive:drive.metadata:readonly`
`file.view_records.list`	`drive:file:view_record:readonly`
`file.comment.reply.reactions.update_reaction`	`docs:document.comment:create`