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

Terminology note: Feishu Cloud Space is also often called "cloud drive", "cloud storage", "netdisk", or "My Space"; these terms usually refer to the same product, which is Feishu's official cloud file storage and management center.

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

Copy routing rule: If the user wants to copy an online document, create a document copy, or copy a document to another folder, you must use lark-cli drive +copy. Do not use drive +export to download and then drive +import upload, and do not use docs +fetch + docs +create to rebuild the body; export/import is only for local file conversion or offline artifacts.

Quick decisions

• The user wants tomove an existing Wiki node out of the knowledge base and place it in a Drive folder or the root directory of "My Space": switch to lark-wiki, use lark-cli wiki +move-to-drive; do not hand the Wiki token directly to drive +move. This is a write operation that changes document ownership and permission inheritance; before executing, confirm the source node and target location.
• The user wants tocopy a document / create a copy to the cloud drive or a folder: when a directly usable URL or token is provided, follow references/lark-drive-copy.md use lark-cli drive +copy; when only a title is provided, first follow references/lark-drive-search.md use drive +search to uniquely locate the source resource, then copy according to the copy reference. If you want to copy a document / create a copy to the knowledge base, use wiki +node-copy(see lark-wiki-node-copy.md）。
• The user wants toidentify the type and token of a Feishu / doubao cloud space URL: you can first make a lightweight judgment based on the URL path shape; when the path already clearly points to resources such as docx / sheet / bitable / slides / file / folder, you can directly extract the corresponding token/type. When a wiki URL is passed in, when the title or canonical URL needs to be identified, when the URL/token is ambiguous, or when subsequent operations depend on the underlying real resource, then use lark-cli drive +inspect --url '<url>' for identification; for specific usage, failure handling, and boundaries, see references/lark-drive-inspect.md。
• High-risk write operations (deletion, public permission changes, owner transfer, version deletion/rollback, batch move/overwrite/sync) must satisfy three conditions simultaneously before execution: the target has been resolved into an execution object directly usable by the operation, the execution details are clear enough to directly invoke the command (for example, the file-token/type for deletion, the sharing scope for public permission changes, the target owner for owner transfer, the version id for version deletion/rollback, and the target location and conflict policy for move/overwrite/sync), and the user explicitly confirms in this turn to execute these specific targets and execution details. When the user only says "delete useless files", "open/share with everyone", "change to open", "overwrite/move these", it only indicates the target state; first perform read-only discovery and list the candidates, permission tiers, or execution plans, then stop and wait for user confirmation.
• The user wants tocheck / govern document permissions, public scope, link sharing, external access, copy and download permissions, security level labels, owner transfer, or wants a "permission risk report, tighten permissions, request view / edit permission, transfer / batch transfer owner", you must first read references/lark-drive-workflow.md, then follow its Workflow Registry to enter permission_governance workflow。
• When the user explicitly wants toremove a single cloud document collaborator's permission, use lark-cli drive +member-remove; first read references/lark-drive-member-remove.md. This is a high-risk write operation; real execution must confirm the exact resource, member ID/type, and wiki permission scope, and explicitly pass --yes。
• When the user wants to, for a specified Feishu document,set / modify the security level label (secure label), or query the security level labels available to the current user, directly read references/lark-drive-secure-label.md; this is a Drive file governance capability.
• The user wants tocheck / govern document permissions, public scope, link sharing, external access, copy and download permissions, security level labels, owner transfer, or wants a "permission risk report, tighten permissions, request view / edit permission, transfer / batch transfer owner", you must first read references/lark-drive-workflow.md, then follow its Workflow Registry to enter permission_governance workflow。
• The user wants toquery the public access, sharing, collaborator management, security, and comment permission settings of a file, folder, or cloud document itself, preferentially use lark-cli drive +permission-get-setting; it only reads the target's own settings and does not recursively audit the permissions of subdocuments in a folder. A bare token must be explicitly passed --type。
• The user wants tosearch across containers for materials by a specific topic, keyword, or content clue, and uniformly collect them into a Drive folder or Wiki node, you must first read references/lark-drive-workflow.md, then follow its Workflow Registry to enter the topic_move_collector workflow. This workflow is responsible for search recall, content verification, relevance classification, move planning, pre-write confirmation, and result verification; it is forbidden to start directly from drive +search or drive +move .
• The user wants toorganize a cloud drive / folder / document library / knowledge base / personal document library, or wants to "inventory the directory structure, find unarchived/temporary/duplicate/empty directories, generate an organization plan", you must first read references/lark-drive-workflow.md, then follow its Workflow Registry to enter the knowledge_organize workflow. By default, only a plan is generated; creating directories, moving resources, and requesting permissions must all be confirmed separately.
• To search across scopes by topic and centrally archive, enter topic_move_collector; to perform directory inventory and structural reorganization on a known folder, document library, or knowledge base, enter knowledge_organize; When moving only one already-specified resource, still use the atomic move command.
• When the user wants tosearch documents / Wiki / spreadsheets / multi-dimensional tables / cloud space (cloud drive/cloud storage) objects, prioritize using lark-cli drive +search; when locating by title and handling duplicate candidates, follow references/lark-drive-search.md. In natural language, "recently edited by me", "created by me" (→ --created-by-me, original creator semantics), "owned by me/owner" (→ --mine, owner semantics), "the xxx I opened in the last week", "docx owned by someone" etc. map directly to flat flags, avoiding hand-written nested JSON.
• When the user wants todocument commentsperform any operation (add comment, list / batch query, reply, get / update / delete reply, resolve / restore, reaction), select the corresponding drive +<verb> comment command according to the Shortcuts table below; read that command's ref before executing. For locating the document body position by comment, see references/lark-drive-comment-location.md。
• When the user provides a doubao.com cloud space resource URL/token, or explicitly mentions a file/folder/docx/sheet/bitable/wiki resource in Doubao, still route to this skill according to resource type, URL path and token; do not fall back to WebFetch just because the domain is not Feishu.
• When the user wants to import a local .xlsx / .csv / .base into a Base / multi-dimensional table / bitable, the first step must use lark-cli drive +import --type bitable。
• When the user wants to import a local .md / .docx / .doc / .txt / .html into an online document, use lark-cli drive +import --type docx。
• When the user wants to import a local .pptx into Feishu Slides, use lark-cli drive +import --type slides; the current PPTX import limit is 500MB.
• When executing drive +import in batch and the target is the same location (same --folder-token, default root directory, or same --target-token), execution must be serial; do not import concurrently to the same location, as the server may return a concurrency conflict error.
• When the user wants to upload, create, read, partially patch or overwrite-update in Drivenative .md files(not import into docx), switch to lark-markdown。
• When the user wants to compare native .md files'historical version differences, or compare remote Markdown with a local draft, switch to lark-markdown 's lark-cli markdown +diff; if a version number is needed, first use drive +version-history。
• When the user wants to view, download, roll back or delete a file'shistorical versions, use drive +version-history、drive +version-get、drive +version-revert、drive +version-delete; this group of commands supports both --as user and --as bot, and automation scenarios should prioritize --as bot。
• When the user wants to import a local .xlsx / .xls / .csv into a spreadsheet, use lark-cli drive +import --type sheet。
• When the user wants to create a new folder in cloud space (cloud drive/cloud storage), prioritize using lark-cli drive +create-folder。
• When the user wants to view or download file content, or view available preview formats for a file and obtain converted preview outputs such as PDF / HTML / text / images, use lark-cli drive +preview。+preview and +download both support --file-token / --url / --wiki-token choose one of three (Wiki will resolve to the underlying file); but the two only handle Drive files; if the target is an online document such as docx/sheet/bitable/slides, switch to drive +export。
• When the user wants to obtain a file's cover image, prioritize using lark-cli drive +cover; first --list-only check the specification, then choose --spec to download.
• When the user wants to export a cloud document, prioritize using lark-cli drive +export --url '<文档 URL>' --file-extension <格式>; for detailed parameters, Wiki token, and error code handling, see references/lark-drive-export.md。
• When the user wants to upload a local file to a wiki node in a knowledge base / document library, still use lark-cli drive +upload --wiki-token <wiki_token>; do not mistakenly switch to the wiki domain command.
• lark-base is only responsible for Base internal operations (tables, fields, records, views) after import is complete; do not switch to it early at the "local file -> Base" step. lark-base。
• When the user gives a wiki URL / token and the underlying resource type has not yet been clarified, first use lark-cli drive +inspect to unwrap;+inspect after a failure, do not automatically switch to another write API and keep trying; first handle permissions, scope, or link issues according to the error message.
• drive +inspect / drive +upload When encountering not found、permission denied、missing scope , stop retrying by default; only rate limit or temporary network errors are suitable for limited retries.

Modify title

• The user wants torename / change title / change file name, use lark-cli drive +update-title, for usage see references/lark-drive-update-title.md。

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, downloading files, etc.), 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 The token in the URL path is used directly as
/doc/	https://example.larksuite.com/doc/doccnxxxxxxxxx	file_token	The token in the URL path is used directly as file_token The token in the URL path is used directly as
/wiki/	https://example.larksuite.com/wiki/wikcnxxxxxxxxx	wiki_token	Cannot be directly used as the underlying file_token; prioritize using drive +inspect to unwrap and obtain obj_token
/sheets/	https://example.larksuite.com/sheets/shtcnxxxxxxxxx	file_token	The token in the URL path is used directly as file_token The token in the URL path is used directly as
/page/	https://example.feishu.cn/page/pagcnxxxxxxxx/	apps token	Use the token in the URL path directly, the resource type is apps
/drive/folder/	https://example.larksuite.com/drive/folder/fldcnxxxx	folder_token	The token in the URL path is used as the folder token

Special Handling for Wiki Links

lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'

Behind a knowledge base link may be different objects such as docx, sheet, bitable, slides, file, etc. When subsequently performing comments, downloads, exports, or content reading, prioritize using drive +inspect to get type、token、title、url; for complete manual parsing and cross-skill routing see the shared document lark-wiki-token-routing.md. Do not guess the underlying type based only on /wiki/<token> .

Common Operation Token Requirements

Operation	Required Token	Description
Read document content	file_token / automatically handled via docs +fetch supports passing the URL directly	docs +fetch supports passing the URL directly
Download file	file_token	Extract directly from the file URL
Upload file	folder_token / wiki_node_token	Token of the target location

Typical Errors and Solutions

Error Message	Cause	Solution
not exist	Used the wrong token	Check the token type; a wiki link 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	According to obj_type Pass the correct file_type (docx/doc/sheet/slides/bitable/apps)
232140101 / 232140100 / 233523001(commonly seen in drive +import of job_error_msg）	concurrent import / create operations exist in the same location	When batch importing to the same folder, root directory, or the same --target-token , switch to serial execution; before each retry of each failed item, wait a few seconds, retry at most 3 times in total, and if it still fails, stop and report the conflict

Permission capabilities entry

• When the user wants to manage Drive document/file collaborators, public permissions, authorize the current app to access a document, or handle permission.public.patch of 91009 / 91010 / 91011 / 91012 errors, first read lark-drive-permission-guide.md。
• When the user wants to query the public access, sharing, collaborator management, security, and comment permission settings of a file, folder, or cloud document itself, use +permission-get-setting; if you need to recursively audit the permissions of subdocuments under a folder, then enter permission_governance workflow。
• If the user simply lacks access permission and wants to request access from the owner, prioritize using +apply-permission。
• Ordinary scope, identity, or login issues are still handled according to lark-shared ; do not simply categorize tenant security policies, external sharing, or classification interception as missing scope.

Not within the scope of this skill

• Reading, summarizing, creating, editing document body, or inserting/downloading images/attachments: use lark-doc。
• In-sheet operations such as spreadsheet cells, filters, formulas, and styles: use lark-sheets。
• Operations within Base / Bitable such as tables, fields, records, views, and dashboards: use lark-base。
• Knowledge space, Wiki node hierarchy, and space member management: use lark-wiki; uploading local files to a wiki node still uses drive +upload --wiki-token。
• Native Markdown file reading, writing, patch, and diff: use lark-markdown; importing Markdown as an online docx is when to use drive +import --type docx。

Shortcuts (recommended first choice)

Shortcut is a high-level wrapper for common operations (lark-cli drive +<verb> [flags]). Prioritize using operations that have a Shortcut.

Shortcut	Description
+search	Search cloud space objects such as documents, Wiki, sheets, and folders; supports --edited-since、--created-by-me、--mine、--doc-types and other flat flags; distinguishes original creator and owner semantics.
+upload	Upload local files to a Drive folder or wiki node; when modifying/rewriting/updating an existing file, prioritize overwrite upload rather than directly uploading a new file.
+create-folder	Create a new Drive folder, supporting parent folders and automatic authorization after bot creation.
+download	Download a Drive file to local.
+preview	View or download file content, or view the available preview formats of a file and obtain converted preview outputs such as PDF / HTML / text / images.
+cover	View or download the file cover image specifications.
+status	Compare differences between a local directory and a Drive folder; by default uses exact SHA-256 comparison,--quick uses modification time for approximate comparison.
+pull	Pull files from Drive to a local directory, supporting duplicate remote path handling and incremental mode.
+sync	Bidirectional sync between a local directory and a Drive folder: pull new_remote, push new_local，modified handled according to --on-conflict=remote-wins|local-wins|keep-both|ask ;--quick uses modification time for approximate comparison;--on-duplicate-remote supports fail / newest / oldest; only sync type=file, skip online documents and shortcuts, and will not delete excess files on either side.
+push	Push a local directory to a Drive folder, supporting skip / smart / overwrite and deleting the remote after confirmation.
+create-shortcut	Create shortcuts to existing Drive files in another folder.
+copy	Copy resources to the target folder; if copying to a wiki space, use wiki +node-copy；
+add-comment	Add full-text/inline comments to doc/docx/file/sheet/slides/base(bitable); Miaoda apps are not supported.
+list-comments	Get the comment list with pagination.
+batch-query-comments	Batch get comments by comment ID.
+resolve-comment	Mark a comment as resolved (is_solved=true）。
+restore-comment	Restore/reopen a resolved comment (is_solved=false）。
+add-reply	Add a reply to an existing comment.
+list-replies	Get the replies under a comment with pagination.
+update-reply	Replace the content of a reply entirely.
+delete-reply	Delete a reply under a comment (high risk, requires --yes）。
+react-reply	Add/remove emoji reactions to a reply.
+export	Export doc/docx/sheet/bitable/slides as local files.
+export-download	Download the file based on the file_token of the export artifact.
+import	Import a local file as a Feishu online document, spreadsheet, bitable, or slides.
+version-history	View the file's historical versions.
+version-get	Download the specified historical version.
+version-revert	Roll back to the specified historical version.
+version-delete	Delete the specified historical version.
+move	Move a Drive file or folder; for Wiki hierarchy moves use lark-wiki。
+update-title	Rename a file, folder, online document, or wiki space.
+delete	Delete a Drive file or folder; folder deletion will poll the async task.
+task_result	Query the results of async tasks such as import/export/move/delete.
+inspect	Inspect the type, title, and canonical token of a URL; wiki URLs are automatically unwrapped to the underlying document.
+apply-permission	Request access permission from the document owner as a user.
+member-add	Add one or up to 10 Drive documents, files, folders, or wiki node collaborators/authorized members; wraps Drive permission member create/batch_create, actual write requires --yes。
+member-list	Query the collaborator/authorized member list of a Drive document, file, folder, or wiki node.
+member-remove	Remove a Drive document, file, folder, or wiki node collaborator; wraps Drive permission member delete, actual write requires --yes。
+permission-get-setting	Query the public access, sharing, collaborator management, security, and comment permission settings of a file, folder, or cloud document itself; supports URL or bare token + --type; does not recursively read folder subdocument permissions.
+secure-label-list	List the classification labels available to the current user.
+secure-label-update	Update the classification label of a Drive file or document.

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.

High-frequency native commands: When reading a Drive folder list, use drive files list, and read references/lark-drive-files-list.mdbefore use, pass parameters via --params according to the template and handle pagination manually; do not pass --page-all output directly to a JSON parsing script.

files

• copy — copy files; prefer using drive +copy
• create_folder — create a folder
• list — get the list under a folder; read references/lark-drive-files-list.md
• patch — modify the file title; prefer using drive +update-title shortcut

permission.members

• auth —
• create — Add collaborator permissions
• 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 users and apps for specified events

file.statistics

• get — Get file statistics
  • When getting docx / file statistics, it is recommended to use typed flags first:lark-cli drive file.statistics get --file-token <token> --file-type <type> --format json；--params JSON is also supported, suitable for batch assembly or raw parameter scenarios.

file.view_records

• list — Get the visitor records of a document
  • To view recent docx visit records, return open_id, and at most N records, it is recommended to use typed flags first:lark-cli drive file.view_records list --file-token <docx_token> --file-type docx --page-size <N> --viewer-id-type open_id --format json；--params JSON is also supported, suitable for batch assembly, paginated continuation, or raw parameter scenarios.

file.comment.reply.reactions

• update_reaction — Add/delete reaction; prefer using drive +react-reply

quota_details

• get — Get the current user's capacity information, including usage for each business, whether the tenant quota is exceeded, user quota, and department quota
  • Only supports --as user, do not use the default bot identity
  • quota_detail_id pass the current user's user_id