lark-drive

drive (v1)

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

Terminology Note: Feishu Cloud Space is also commonly referred to as "Cloud Drive," "Cloud Storage," "Network Drive," or "My Space." These terms generally refer to the same product, which is the official Feishu cloud-based file storage and management center.

Import Routing Rule: If a user wants to import a local Excel / CSV / .base snapshot into Base / Bitable, you must prioritize using lark-cli drive +import --type bitable. Do not switch to lark-base first; lark-base is only responsible for operations within the table after the import is complete.

Quick Decision Making

• If a user wants to check / govern document permissions, public visibility, link sharing, external access, copy/download permissions, security labels, or owner transfer, or needs a "permission risk report, tightening of permissions, requesting view / edit access, or transferring / batch transferring ownership," you must first read references/lark-drive-workflow.md and then enter the permission_governance workflow via the Workflow Registry.
• If a user wants to organize their Cloud Drive / folders / document libraries / knowledge bases / personal document libraries, or needs to "audit directory structure, identify unarchived/temporary/duplicate/empty directories, or generate an organization plan," you must first read references/lark-drive-workflow-knowledge-organize.md. By default, only generate a plan; creating directories, moving resources, and requesting permissions must be confirmed separately.
• If a user wants to search for documents / Wiki / spreadsheets / Bitable / Cloud Space (Cloud Drive/Cloud Storage) objects, prioritize using lark-cli drive +search. In natural language, "recently edited by me," "created by me" (→ --created-by-me, original creator semantics), "managed/owned by me" (→ --mine, owner semantics), "xxx I opened in the last week," "docx owned by someone," etc., map directly to flat flags to avoid manual nested JSON.
• If a user wants to locate text based on document comments, such as reviewing a document based on comments, looking back at a document based on comment content, or distinguishing between multiple identical cited texts, docx type (file_type=docx) documents support returning comment locations via need_relation=true. Other types are not currently supported. For specific usage, read references/lark-drive-comment-location.md first.
• If a user provides a doubao.com Cloud Space resource URL/token, or explicitly mentions a file/folder/docx/sheet/bitable/wiki resource in Doubao, route to this skill based on the resource type, URL path, and token; do not fall back to WebFetch just because the domain is not Feishu.
• If a user wants to import a local .xlsx / .csv / .base into Base / Bitable, the first step must be using lark-cli drive +import --type bitable.
• If a user wants to import a local .md / .docx / .doc / .txt / .html into an online document, use lark-cli drive +import --type docx.
• If a user wants to import a local .pptx into Feishu Slides, use lark-cli drive +import --type slides; the current PPTX import limit is 500MB.
• If a user wants to upload, create, read, partially patch, or overwrite update native .md files (not imported as docx) in Drive, switch to lark-markdown.
• If a user wants to compare historical version differences of native .md files, or compare a remote Markdown with a local draft, switch to lark-cli markdown +diff in lark-markdown; use drive +version-history first if a version number is needed.
• If a user wants to view, download, roll back, or delete historical versions of a file, use drive +version-history, drive +version-get, drive +version-revert, or drive +version-delete; this set of commands supports both --as user and --as bot, with --as bot preferred for automation scenarios.
• If a user wants to import a local .xlsx / .xls / .csv into a spreadsheet, use lark-cli drive +import --type sheet.
• If a user wants to create a new folder in Cloud Space (Cloud Drive/Cloud Storage), prioritize using lark-cli drive +create-folder.
• If a user wants to see which downloadable/previewable formats are available for a file, or wants to download PDF / HTML / text / image preview artifacts, use lark-cli drive +preview.
• If a user wants to get a cover image for a file, prioritize using lark-cli drive +cover; use --list-only first to check specifications, then select --spec to download.
• If a user wants to upload a local file to a specific wiki node in a knowledge base / document library, still use lark-cli drive +upload --wiki-token <wiki_token>; do not mistakenly switch to wiki domain commands.
• If the user provides a wiki URL / token and the underlying resource type is not yet explicitly known, use lark-cli drive +inspect to unpack it first; do not automatically switch to other write interfaces if +inspect fails, handle permissions, scope, or link issues according to the error prompt first.
• If drive +inspect / drive +upload encounters not found, permission denied, or missing scope, stop retrying by default; only rate limit or temporary network errors are suitable for limited retries.

Modify Title

• Use the drive files patch command and the new_title field to modify the title. This supports docx, sheet, bitable, file, wiki, and folder types.

Core Concepts

Document Types and Tokens

In the Feishu Open Platform, different document types 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

Wiki Link Special Handling

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

Behind a knowledge base link could be a docx, sheet, bitable, slides, file, or other object. When performing subsequent comments, downloads, exports, or content reading, prioritize using drive +inspect to get the type, token, title, and 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 solely on /wiki/<token>.

Common Operation Token Requirements

Comment Capability Entry

• For adding comments, prioritize using +add-comment: in review / proofreading scenarios, default to creating partial comments whenever possible; do not merge multiple locatable issues into one full-text comment.
• For comment queries, statistics, sorting, and reply restrictions, read lark-drive-comments-guide.md first.
• When you need to locate text based on comments, confirm the target is file_type=docx first, then read lark-drive-comment-location.md; other document types do not currently support returning location fields.
• For reaction / emoji-related operations, read lark-drive-reactions.md first; only include need_reaction=true when the user explicitly requires reaction information.
• The --content for drive +add-comment requires a reply_elements JSON array string, e.g., --content '[{"type":"text","text":"body"}]'.
• slides comments require explicitly passing --block-id <slide-block-type>!<xml-id>; the CLI will split this and write it into anchor.block_id and anchor.slide_block_type. The <xml-id> is the element id in the PPT XML protocol; --selection-with-ellipsis and --full-comment are not supported.
• Text content in comments (adding comments, replying to comments, editing replies) cannot directly contain < or >; they must be escaped before submission: < -> <, > -> >.
• When using drive +add-comment, the shortcut automatically performs the above escaping for type=text elements; if calling drive file.comments create_v2, drive file.comment.replys create, or drive file.comment.replys update directly, you must pass the escaped content in the request yourself.
• Base record partial comments use --type bitable / --type base or /base/, /bitable/, or wiki Base links; bitable and Base are the same concept, bitable is the internal code, Base is the product name. It is recommended to pass bitable for raw tokens; base is only used as a compatibility alias.
• Base does not support global comments; all comments are attached to records. Positioning information must be file token (base token) + --block-id <table-id>!<record-id>!<view-id>, where table/record/view IDs usually start with tbl/rec/vew respectively. The view_id only determines which view opens when clicked from a notification; it does not affect the comment attachment point. Comments are visible on the same record regardless, but it must be passed, otherwise the notification cannot determine which view to jump to. IDs can be obtained via lark-base.
• If the wiki resolves to something other than doc/docx/file/sheet/slides/bitable/base, do not use +add-comment.
• If you need to call the comment V2 protocol directly at a lower level, use the native API: execute lark-cli schema drive.file.comments.create_v2 first, then execute lark-cli drive file.comments create_v2 .... Omit anchor for full-text comments; for docx/sheet/slides partial comments, pass anchor.block_id; for Base record partial comments, pass anchor.block_id (table_id), anchor.base_record_id, and anchor.base_view_id.
• When calling native drive.file.comments.* / drive.file.comment.replys.* to comment on Base documents, set file_type to bitable, not base.

Typical Errors and Solutions

Permission Capability Entry

• If a user wants to manage Drive document/file collaborators, public permissions, authorize the current application to access a document, or handle 91009 / 91010 / 91011 / 91012 errors from permission.public.patch, read lark-drive-permission-guide.md first.
• If the user simply lacks access and wishes to request access from the owner, prioritize using +apply-permission.
• General scope, identity, or login issues are still handled according to lark-shared; do not simply classify tenant security policies, external sharing, or security level interception as missing scope.

Out of Scope for This Skill

• Document body reading, summarization, creation, editing, image/attachment insertion or download: use lark-doc.
• Spreadsheet cell, filtering, formula, style, and other in-table operations: use lark-sheets.
• Base / Bitable internal table, field, record, view, dashboard, and other operations: use lark-base.
• Knowledge space, Wiki node hierarchy, space member management: use lark-wiki; uploading local files to wiki nodes still uses drive +upload --wiki-token.
• Native Markdown file reading, writing, patching, diffing: use lark-markdown; only use drive +import --type docx to import Markdown as an online docx.

Shortcuts (Recommended)

Shortcuts are high-level encapsulations of common operations (lark-cli drive +<verb> [flags]). Prioritize using operations that have shortcuts.

API Resources

lark-cli schema drive.<resource>.<method>   # Must view parameter structure before calling API
lark-cli drive <resource> <method> [flags] # Call API

Important: When using native APIs, you must run schema first to view the --data / --params parameter structure; do not guess field formats.

High-Frequency Native Commands: When reading a Drive folder list, use drive files list. You must pass folder_token / page_token via --params according to the template in references/lark-drive-files-list.md and handle pagination manually; do not pass --page-all output directly to JSON parsing scripts.

files

• copy, Copy file
• create_folder, Create new folder
• list, Get list under a folder; read references/lark-drive-files-list.md before use
• patch, Modify file title

file.comments

• batch_query, Batch get comments
• create_v2, Add full-text/partial (highlight) comment
• list, Get document comments by page
• 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/application dimension events
• subscription, Subscribe to user/application dimension events (comment addition events are open this time)
• subscription_status, Query subscription status of user/application for specified events

file.statistics

• get, Get file statistics

file.view_records

• list, Get visitor records for a document

file.comment.reply.reactions

• update_reaction, Add/delete reaction

quota_details

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