lark-drive

drive (v1)

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

Import Routing Rules: If a user wants to import a local Excel / CSV / .base snapshot into a 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

• To search for documents / Wiki / spreadsheets / Bitable / Drive objects, prioritize using lark-cli drive +search. In natural language, requests like "recently edited by me," "created by me," "opened by me in the last week," or "docx created by someone" map directly to flat flags, avoiding manual nested JSON. The old docs +search is in maintenance mode and will be deprecated; do not add new dependencies on it.
• To import a local .xlsx / .csv / .base into a Base / Bitable, the first step must be lark-cli drive +import --type bitable.
• To import a local .md / .docx / .doc / .txt / .html into an online document, use lark-cli drive +import --type docx.
• To upload, create, read, patch, or overwrite native .md files in Drive (not importing as docx), switch to lark-markdown.
• To view, download, roll back, or delete historical versions of a file, use drive +version-history, drive +version-get, drive +version-revert, and drive +version-delete. This set of commands supports both --as user and --as bot; for automation scenarios, prioritize --as bot.
• To import a local .xlsx / .xls / .csv into a spreadsheet, use lark-cli drive +import --type sheet.
• To create a new folder in Drive, prioritize using lark-cli drive +create-folder.
• To upload a local file to a specific wiki node in a knowledge base, continue to use lark-cli drive +upload --wiki-token <wiki_token>; do not mistakenly switch to wiki domain commands.
• lark-base is only responsible for internal Base operations (tables, fields, records, views) after the import is complete. Do not switch to lark-base prematurely during the "local file to Base" step.

Modify Title

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

Core Concepts

Document Types and Tokens

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

Wiki Link Special Handling (Critical!)

Knowledge base links (/wiki/TOKEN) may point to different types of documents such as cloud documents, spreadsheets, or Bitables. Do not assume the token in the URL is the file_token. You must query the actual type and real token first.

Processing Flow

1. Use wiki.spaces.get_node to query node information

   lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
   

2. Extract key information from the result

   • node.obj_type: Document type (docx/doc/sheet/bitable/slides/file/mindnote)
   • node.obj_token: The real document token (used for subsequent operations)
   • node.title: Document title

3. Use the corresponding API based on obj_type

   obj_type	Description	API to Use
   docx	New cloud document	drive file.comments.*, docx.*
   doc	Old cloud document	drive file.comments.*
   sheet	Spreadsheet	sheets.*
   bitable	Bitable	bitable.*
   slides	Slides	drive.*
   file	File	drive.*
   mindnote	Mindnote	drive.*

Query Example

# Query wiki node
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

Example return result:

{
  "node": {
    "obj_type": "docx",
    "obj_token": "xxxx",
    "title": "Title",
    "node_type": "origin",
    "space_id": "12345678910"
  }
}

Resource Relationships

Wiki Space
└── Wiki Node
    ├── obj_type: docx (New doc)
    │   └── obj_token (Real document token)
    ├── obj_type: doc (Old doc)
    │   └── obj_token (Real document token)
    ├── obj_type: sheet (Spreadsheet)
    │   └── obj_token (Real document token)
    ├── obj_type: bitable (Bitable)
    │   └── obj_token (Real document token)
    └── obj_type: file/slides/mindnote
        └── obj_token (Real document token)

Drive Folder
└── File (File/Document)
    └── file_token (Use directly)

Common Token Requirements for Operations

Comment Capability Boundaries (Critical!)

• drive +add-comment supports two modes.

• Full-text comment: Enabled by default if --block-id is not passed, or can be explicitly passed via --full-comment; supports docx, old doc URLs, and wiki URLs that resolve to doc/docx.

• Partial comment: Enabled when passing --block-id; only supports docx and wiki URLs that resolve to docx. Block IDs can be obtained via docs +fetch --api-version v2 --detail with-ids.

• The --content for drive +add-comment requires a reply_elements JSON array string, for example --content '[{"type":"text","text":"Body text"}]'.

• 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; it does not support --selection-with-ellipsis or --full-comment.

• Text content written in comments (adding comments, replying to comments, editing replies) cannot contain < or > directly; 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.

• If the wiki resolution is not doc/docx/sheet/slides, do not use +add-comment.

• If you need to call the comment V2 protocol at a lower level, use the native API: first execute lark-cli schema drive.file.comments.create_v2, then execute lark-cli drive file.comments create_v2 .... Omit anchor for full-text comments, and pass anchor.block_id for partial comments.

Comment Query and Statistics (Critical!)

Mandatory Rule: drive file.comments list must pass is_solved:false by default, meaning only query unresolved comments. Even if the user says "all comments" or "list all comments," as long as they do not explicitly mention including resolved comments, continue to query unresolved comments by default. Only omit the is_solved parameter when the user explicitly requests to include resolved comments.

Correct Example:

# Default query: only unresolved comments (recommended)
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'

# Query all comments (user did not explicitly request resolved comments)
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'

# Include resolved comments (requires explicit user request)
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'

Incorrect Example:

# Not recommended: querying all comments when the user did not explicitly request it
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'

• When querying document comments, use drive file.comments list.
• The items returned by drive file.comments list should be understood as a list of "comment cards." Each item corresponds to one comment card seen in the user interface, not a flattened list of interactive messages.
• In server semantics, creating the first comment also creates the first reply in that card; therefore, the actual body text is contained in each item.reply_list.replies, where the first reply is the "comment itself" from the user's perspective.
• When the user wants to count "number of comments" or "number of comment cards," count the length of items; for a full count, accumulate the lengths of items across all paginated results.
• When the user wants to count "number of replies," from the user's perspective, exclude the first comment in each comment card. The counting logic is the sum of the lengths of all item.reply_list.replies minus the number of items.
• When the user wants to count "total interactions," count the sum of the lengths of all item.reply_list.replies; this count includes the first comment in each comment card.
• If an item.has_more=true, it means there are more replies under that comment card not included in the current return; in this case, you need to continue calling drive file.comment.replys list to fetch the full list before performing the full reply count / total interaction count.

Comment Business Characteristics and Guidance (Critical!)

Comment Sorting Guidance

• A document usually has multiple comments, sorted by create_time.
• Important: Only sort by create_time when the user explicitly mentions "latest comment," "last comment," or "earliest comment":
  • Must fetch all comments first (process pagination to get all data); do not 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 just says "first comment," use the first one returned by drive file.comments list directly without extra sorting.

Comment Reply Restrictions

• Check for the following restrictions before adding a comment reply.
• Full-text comments do not support replies: Comments with is_whole=true cannot be replied to. If you encounter such comments, inform the user that "Full-text comments do not support replies."
• Resolved comments do not support replies: Comments with is_solved=true cannot be replied to. If you encounter such comments, inform the user that "This comment has been resolved and cannot be replied to."
• Note: When a user wants to reply to a comment that cannot be replied to due to the above restrictions, only inform them that it cannot be replied to. Do not automatically help the user find other comments to reply to, to avoid violating user expectations.

Batch Query vs. List Query

• Use drive file.comments batch_query for batch queries after the comment IDs are known; it requires passing a specific list of comment IDs.
• Use drive file.comments list for paginated retrieval of comment lists, suitable for counting total comments, traversing all comments, or scenarios like getting the "latest/last N comments."

Reaction / Emoji Scenarios

• When encountering questions related to reactions on comments/replies (emojis, counts, who clicked what, adding/deleting emojis), read lark-drive-reactions.md first to understand how to use them.

Typical Errors and Solutions

permission.public.patch Error Code Guidance

When calling lark-cli drive permission.public patch to update document public permissions fails, if the following error codes are returned, provide clear next steps to the user based on the table. Do not simply categorize these errors as missing scopes; they usually indicate interception by tenant, external sharing, or document security classification policies.

When the user initially provides a document URL and encounters 91011 or 91012, return that URL to the user as the operation entry point. If the context only has a token, try to restore the target document URL using existing context, search results, or metadata before providing the clickable document URL.

Authorizing the Current Application to Access Documents

When you need to grant document permissions to the current application (bot) itself, first obtain the application's open_id via the bot info interface, then call the permission interface to authorize:

# 1. Get the current application's open_id
lark-cli api GET /open-apis/bot/v3/info --as bot
# Get bot.open_id from the return value

# 2. Authorize the current application to access the document
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 you need to authorize the current application. When authorizing other users, use their open_id directly; there is no need to call the bot info interface.

<resource_type> optional values: doc, docx, sheet, bitable, file, folder, wiki, slides.

Shortcuts (Recommended)

Shortcuts are high-level wrappers for common operations (lark-cli drive +<verb> [flags]). Prioritize using shortcuts when available.

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.

files

• copy, Copy file
• create_folder, Create new folder
• list, Get list under folder
• patch, Modify file title

file.comments

• batch_query, Batch get comments
• create_v2, Add full-text/partial (highlight) comment
• list, Paginated retrieval of document comments
• 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 event enabled this time)
• subscription_status, Query subscription status of user/application for specified events

file.statistics

• get, Get file statistics

file.view_records

• list, Get document visitor records

file.comment.reply.reactions

• update_reaction, Add/delete reaction

Permission Table