wecomcli-disk

wecom-cli is a tool provided by the plugin, not a terminal command: all operations are completed by calling this tool, and parameters should be passed using args It is forbidden to use it via command-line methods such as exec / shell / terminal.

⚠️ Prerequisite: Before calling wecom-cli for the first time, the prerequisite check must be performed according to the wecomcli-preflight skill to ensure the tool has been added to the allowlist.

WeCom Drive

Resource-type skill responsible for listing, searching, reading information, uploading, downloading, renaming, and creating folders for WeCom Drive files.

Scope of application

Applicable

• List recently viewed files in WeCom Drive
• Search WeCom Drive files or folders by keyword/type/creator/shared space
• Read basic information of WeCom Drive files
• Upload local files to a specified folder in WeCom Drive
• Download WeCom Drive files to local
• Rename WeCom Drive files
• Create a new folder in WeCom Drive

Not applicable

• Move WeCom Drive files or folders → Inform the user that this is not yet supported and suggest manually operating in the WeCom client
• Delete WeCom Drive files / copy WeCom Drive files → Inform the user that this is not yet supported and suggest manually operating in the WeCom client
• Delete / rename WeCom Drive folders (folder), adjust the directory tree structure → Inform the user that this is not yet supported and suggest manually operating in the WeCom client
• Create / delete shared spaces (space), modify space members and space settings → Inform the user that this is not yet supported and suggest manually operating in the WeCom client
• Grant the bot permission to a space / add the bot as a member of a shared space → WeCom Drivedoes not havethis feature, and it cannot be done through any channel (not even the client).It is forbiddento make such suggestions to the user, and do not guide the user to "contact the space administrator to authorize the bot"
• Modify file sharing permissions, generate sharing links, revoke sharing, set access passwords / expiration dates → Inform the user that this is not yet supported and suggest manually operating in the WeCom client
• WeCom Drive file version management (view historical versions, restore old versions, compare versions) → Inform the user that this is not yet supported
• Revoke / modify uploaded files (overwrite upload / instant upload / resumable upload) → Inform the user that this is not yet supported; if replacement is needed, please upload a new file again via "Upload File"
• Parse thecontentof WeCom Drive files (body text extraction, OCR, image Q&A, PDF/Word/Excel parsing, etc.) → This skill is responsible for downloading the file locally to obtain file_path
• Transcription or subtitle generation for video / audio files → Inform the user that this is not yet supported
• Continuously monitor WeCom Drive changes / notify in real time when new files arrive → Cannot actively monitor; do not promise "I will let you know when there are new files"; ask the user to proactively initiate a query again later

Routing decision (determine whether this skill / another skill)

User input signal	Route to
Explicitly mention "WeDrive / cloud drive / disk / WeCom cloud drive"	this skill
Provide https://drive.weixin.qq.com/s?k=... link (WeDrive share URL)	this skill (as the get / download 's url input parameter)
Provide https://doc.weixin.qq.com/<doc|sheet|smartsheet|smartpage>/... link	corresponding to wecomcli-doc / wecomcli-sheet / wecomcli-smartsheet / wecomcli-smartpage
online document doc / sheet / smartsheet / smartpage 's read/write content	same as above, corresponding document skill
Change document permissions / add members / change document name (for doc/sheet/smartsheet/smartpage)	wecomcli-doc-manage

Note:doc.weixin.qq.com / page.weixin.qq.com is the online document domain,drive.weixin.qq.com is the WeDrive domain; do not mix them up.

File type enum

doc(online document),sheet(online spreadsheet),ppt(online slides),collect(collection form),mind(mind map),flow(flowchart),smartsheet(smart sheet),smartpage(smart page),journal(report),pdf（PDF）、offline_word(offline Word),offline_excel(offline Excel),offline_ppt(offline PPT),offline_pdf(offline PDF),image(image),videoaudio(video/audio),design(design draft). Online documents keep their original names; offline files use the offline_ prefix to distinguish them. Tencent Docs is not within the scope of this skill; follow the [Routing Decision] table to switch to the corresponding document skill.

Search both when online/offline is ambiguous: When the user says "Excel", "Word", "PPT", "PDF", etc. without specifying online or offline,file_types pass both the online and offline versions (e.g., ["sheet", "offline_excel"]) to avoid omissions. For other types, pass them literally according to the enum names above.

API details

List files

Get the list of files recently viewed by the user in WeDrive, with pagination support.

How to call

Use the wecom-cli tool to call in the following format

wecom-cli disk files list --json '{"limit": 10}'

Input parameters

Field	Type	Required	Default value	Description
cursor	string	No	""	Pagination cursor; if not provided or an empty string is provided, the first page of data is retrieved
limit	number	No	10	Maximum number of items returned per page; if not provided, the service default is used, maximum 100

Return

Field	Type	Description
has_more	boolean	Whether there is more data;true when next_cursor is used to continue fetching
next_cursor	string	Next page cursor
files[].id	string	File ID or folder ID
files[].file_name	string	File name
files[].docid	string	Document ID, meaningful only when type=smartsheet / smartpage / sheet / word / ppt / collect / journal is meaningful when
files[].type	string	File type:file / folder / space / smartsheet / smartpage / sheet / word / ppt / collect / journal / flow / mind
files[].file_size	number	File size (bytes); meaningful only when type=file is meaningful when
files[].creator_userid	string	Creator userid
files[].space_id	string	Shared space ID it belongs to
files[].space_name	string	Shared space name it belongs to
files[].folder_id	string	Folder ID it belongs to
files[].folder_name	string	Folder name it belongs to
files[].create_time	string	Creation time,YYYY-MM-DD HH:mm:ss
files[].update_time	string	Last update time,YYYY-MM-DD HH:mm:ss
files[].path	string	Full file path
files[].doc_url	string	Document open link, filled only for online document types (smartsheet / smartpage / sheet / word / ppt / collect / journal)

Search files

Search WeDrive files, folders, or shared spaces by keyword, file type, creator, shared space, sort order, and other conditions.

Usage

Use the wecom-cli tool in the following format

wecom-cli disk files search --json '{"keywords": ["季度汇报"], "search_type": "file", "sort_by": "modify_time", "sort_order": "desc", "limit": 10}'

Input parameters

Field	Type	Required	Default	Description
keywords	string[]	Optional	—	Array of literal keywords, length 0-20 (OR relationship); with creator_userids / search_type / file_types choose one of four, at least one required
creator_userids	string[]	Optional	—	Limit creator userid list, length 0-50, no filtering if not provided; with keywords / search_type / file_types choose one of four, at least one required; when the user provides a name, resolve it via wecomcli-contact to userid
search_type	string	Optional	all	Query scope enum:all / file(file) / folder(folder) / space(shared space); with keywords / creator_userids / file_types choose one of four, at least one required；
file_types	string[]	Optional	—	Limit file types, length 0-10; options doc / sheet / ppt / collect / mind / flow / smartsheet / smartpage / journal / pdf / offline_word / offline_excel / offline_ppt / offline_pdf / image / videoaudio / design(online documents keep their original name, offline documents use the offline_ prefix to distinguish); values outside the enum must not be passed; with keywords / creator_userids/ search_type choose one of four, at least one required
space_keywords	string[]	No	—	Limit keyword for the name of the space it is in, length 0-10, OR relationship; matching spaces will be used as the search scope; if not provided, no space limit;Additional filter condition; cannot trigger a search on its own
sort_by	string	No	best_match	Sort order:best_match / modify_time / file_size; values outside the enum must not be passed
sort_order	string	No	desc	Sort direction:asc / desc; only required when sort_by=modify_time or file_size must be passed
cursor	string	No	—	Batch incremental key retrieval, the next_cursorreturned by the previous request; if not provided, start from the beginning
limit	number	No	10	Maximum number of items returned per page, maximum 100

Return

Field	Type	Description
has_more	boolean	Whether there is more data;true when true, use next_cursor to continue fetching
next_cursor	string	Next page cursor
files[].id	string	WeDrive file ID / folder ID / space ID
files[].type	string	Matched item type:file / folder / space / smartsheet / smartpage / sheet / word / ppt / flow / mind / journal / collect
files[].file_name	string	Name (file name / folder name / space name)
files[].file_size	number	File size (bytes), only meaningful when type=file is meaningful when
files[].creator_userid	string	Creator userid
files[].space_id	string	ID of the shared space it is in
files[].space_name	string	Name of the shared space it is in
files[].folder_id	string	ID of the parent folder it is in; equals space_id
files[].folder_name	string	Name of the folder it is in
files[].path	string	Full file path;space_name and folder_name if they have the same name are not necessarily in a parent-child relationship and may be at the same level; use path to determine the hierarchy
files[].create_time	string	Creation time,YYYY-MM-DD HH:mm:ss
files[].update_time	string	Last update time,YYYY-MM-DD HH:mm:ss
files[].docid	string	Document ID, only meaningful when type=smartsheet / smartpage / sheet / word / ppt / collect / journal is meaningful when
files[].doc_url	string	Document open link, only populated for online document types;can be sent directly to users/groups as an online document sharing link, no additional processing needed
files[].title_highlight	string[]	Highlighted summary snippet where the title matches the keyword;type=space is empty when
files[].text_highlight	string[]	Highlighted summary snippet where the body matches the keyword;type=space is empty when

Online document hit handling constraints—extremely important: the type returned by search, if it is smartsheet / smartpage / sheet / word / ppt / journal / collect / mind / flow, these areonline collaborative documents(body stored in the cloud, not binary files),forbiddento go through disk files download(will fail or get an empty shell), and also not suitable to go through disk files get. Among them, smartsheet / smartpage / sheet / word has a corresponding downstream skill that can read the body, see the [Cross-Skill Dependencies] table at the end for routing;ppt / journal / collect / mind / flow currently no downstream skill or CLI can read the body, when these types are hit and the user wants to see the content, directly inform them that reading is not currently supported, and guide the user to use doc_url to open and view it in the WeCom client. Only when type=file can id be used as file_id to call disk files download to get the local file.

Usage Rules

• Trigger conditions (sole authoritative description)：keywords / creator_userids / search_type / file_types Choose one of four, pass at least one；space_keywords is only an additional filter condition,cannot trigger search on its own. If all four are empty, use natural language to ask a follow-up question before initiating the search. If the user only gives a space keyword (e.g., "search in the XX space"), you can use natural language to ask for the specific search content.

• If multiple searches fail, inform truthfully: when there are still no results after adjusting keywords/types multiple times, stop searching and truthfully tell the user whether it is "cannot find the file" or "cannot find that space"; do not repeatedly change words and force searches.

• Optional parameter value strategy—by default do not pass, only pass when the user explicitly names it：

  Parameter	When not to pass (backend default)	When to pass (when the user explicitly expresses it)
  search_type	User vaguely says "search for xxx / find xxx / file / material" etc. without specifying the object type → backend follows all	Explicitly says "only search folders / directories" →folder; "only search shared spaces / team spaces" →space; "only files, not folders" →file
  sort_by	User has no sorting preference → backend follows best_match	"latest / recently modified / earliest" →modify_time; "largest / smallest" →file_size
  sort_order	sort_by=best_match no need to pass when	Pass modify_time / file_size when new→old use desc, old→new use asc; if not passed, default desc
  file_types	User vaguely says "document / file / material / materials" or a business concept (contract / report / meeting minutes) → do not filter, rely on keywords to fulfill	User explicitly names a specific form (PPT / Excel / PDF / image / smart sheet, etc.), put the corresponding enum into the array as well
  space_keywords	When not limited to a space	User says "search in XX space / XX team drive" → fill in the space name keyword (this API does not accept space_id）

• keywords Do not mix in file type suffixes: When the user says "search for Excel reports" or "find PPT proposals", leave the file type suffixes (Excel/PPT/Word/PDF) to file_types for filtering,keywords and keep only the business keywords (such as "report" or "proposal"). Example: "Excel reports" → keywords:["报告"] + file_types:["sheet","offline_excel"]。

• file_types Colloquial-to-enum mapping: See the "User colloquial expressions" column in the "File type enum" table above.

• Pagination continuation：has_more=true use next_cursor as the cursorfor the next call; for the first call, cursor pass an empty string.

• Time range filtering is not supported: This API has no begin_time / end_time field, and forging one is prohibited; if the user provides a time range such as "last 3 days / last week / this month", first fetch by sort_by=modify_time, sort_order=desc , then have the client perform secondary filtering based on update_time .

• Result summary order follows the sort direction：sort_order=desc(default, newest→oldest), the results summarized to the user should also be displayed from newest to oldest; do not reverse the order.

Read file information

Based on file_id or a WeDrive file URL, read basic file information.

How to call

Use the wecom-cli tool to call in the following format

wecom-cli disk files get --json '{"file_id": "FILE_ID"}'

Input parameters

Field	Type	Required	Default value	Description
file_id	string	Choose one of the two	—	File ID; choose one of the two with url takes precedence file_id
url	string	Choose one of the two	—	WeDrive file share URL (in the form https://drive.weixin.qq.com/s?k=AJEAIQdfAAoN4N17GM); choose one of the two with file_id Choose one

Returns

Field	Type	Description
file.id	string	File ID or folder ID
file.file_name	string	File name
file.docid	string	Document ID, only type=smartsheet / smartpage / sheet / word / ppt / collect / journal is meaningful when
file.type	string	File type:file / folder / space / smartsheet / smartpage / sheet / word / ppt / collect / journal / flow / mind
file.file_size	number	File size (bytes); only type=file is meaningful when
file.creator_userid	string	Creator userid
file.space_id	string	Owning shared space ID
file.space_name	string	Name of the shared space it is in
file.folder_id	string	ID of the folder it is in; may be folder file_id or space space_id
file.folder_name	string	Name of the folder it is in
file.create_time	string	Creation time,YYYY-MM-DD HH:mm:ss
file.update_time	string	Last update time,YYYY-MM-DD HH:mm:ss
file.path	string	Full file path
file.doc_url	string	Document open link, filled only for online document types (smartsheet / smartpage / sheet / word / ppt / collect / journal)

Upload file

Upload a local file to the specified directory in WeDrive. Two upload methods are supported:A. Material method When media_id already exists in the context, pass file_content_media；B. Local path method Pass file_pathdirectly. Choose one of the two.

How to call

Use the wecom-cli tool to call in the following format

wecom-cli disk files upload --json '{"folder_id": "FOLDER_ID", "file_name": "季度汇报.pptx", "file_content_media": "mcxxx"}'

Or use the local file path directly:

wecom-cli disk files upload --json '{"folder_id": "FOLDER_ID", "file_name": "季度汇报.pptx", "file_path": "/tmp/季度汇报.pptx"}'

Input parameters

Field	Type	Required	Default value	Description
folder_id	string	No	—	Target folder ID; you can pass folder file_id or space space_id; if not passed, it will be uploaded to the default space by default
file_name	string	Conditionally required	—	File name (including extension); length 1~255; forbidden to contain characters / \ : * ? " < > |; when passing file_path , if not passed, it will be automatically extracted from the path; when passing file_content_media , it is required
file_content_media	string	Choose one	—	The file material's media_id(prefix mc), forbidden to construct or guess on your own; choose one of it and file_path Choose one of the two
file_path	string	Choose one	—	Absolute path of the local file; choose one of it and file_content_media ; one of the two must be provided

Return

Field	Type	Description
file.id	string	File ID after upload
file.file_name	string	File name
file.docid	string	Document ID, meaningful only when type=smartsheet / smartpage / sheet / word / ppt / collect / journal is meaningful when
file.type	string	File type
file.file_size	number	File size (bytes); meaningful only when type=file is meaningful when
file.creator_userid	string	Creator userid
file.space_id	string	Shared space ID it belongs to
file.space_name	string	Shared space name it is in
file.folder_id	string	Folder ID it is in
file.folder_name	string	Folder name it is in
file.create_time	string	Creation time
file.update_time	string	Last update time
file.path	string	Full file path
file.doc_url	string	Document open link, filled only for online document types

Usage rules

Uploading has two paths; just choose one according to the form of the material the user has:

Path A: Material method (file_content_media）

Applicable scenario: In the contextthere is already an available media_id(returned by a preceding skill, or directly provided by the user), no need to go through media +upload。

1. Confirm folder_id: if the user does not provide it and it is not passed, it will be uploaded to the default space by default
2. Directly fill the existing media_id into file_content_media, call disk files upload

Path B: Local path method (file_path）

1. When the user has explicitly provided a local file path (or a preceding skill returned a local file_path, for example disk files download the path after download), it can be used directly
2. Confirm folder_id: if the user does not provide it and it is not passed, it will be uploaded to the default space by default
3. Directly fill the local path into file_path, call disk files upload(no need to go through wecomcli-media）

Choose one, mutually exclusive：file_content_media and file_path only one of them can be selected; they cannot be passed at the same time, nor can both be omitted. When the user has provided neither media_id nor a local file path, ask with natural language; it is forbidden to make one up by searching/hallucinating a file.

Download file

Download a WeDrive file to the local machine and return the local file path.

Call method

Use the wecom-cli tool to call according to the following format

wecom-cli disk files download --json '{"file_id": "FILE_ID"}'

Input parameters

Field	Type	Required	Default value	Description
file_id	string	Choose one of the two	—	ID of the file to download, choose one of the two with url ; if not provided, url
url	string	Choose one of the two	—	File URL, choose one of the two with file_id ; if not provided, file_id

Return

Field	Type	Description
file_path	string	File path returned after the framework saves it as a local file
file_content	string	File content (returned directly as a string when the content is not long)
size	number	File size, in bytes

Usage rules

• Only applies to offline binary files: only type=file(corresponding to the file_types in offline_word / offline_excel / offline_ppt / offline_pdf / image / videoaudio / design) can be downloaded locally through this interface.
• Online document forms never go through download: if the type returned by search is smartsheet / smartpage / sheet / word / ppt / journal / collect / mind / flow，Forbiddento pass their id or doc_url as file_id / url into this interface; it will fail or return an invalid file. Among them, smartsheet / smartpage / sheet / word to read the content, follow the [Cross-skill dependencies] table at the end of the document and use docid to route to the corresponding downstream document skill;ppt / journal / collect / mind / flow currentlyhas no downstream skill that can read the body text, directly tell the user it is not supported for now, and guide them to use doc_url to open and view it in the WeCom client.
• URL form identification: only https://drive.weixin.qq.com/s?k=... is a WeDrive file sharing URL and can be used as the url parameter;https://doc.weixin.qq.com/... / https://page.weixin.qq.com/... are all online document links, and are forbidden to be passed into this interface.

Rename file

Modify the name of a WeDrive file.

How to call

Use the wecom-cli tool to call in the following format

wecom-cli disk files rename --json '{"file_id": "FILE_ID", "new_name": "新文件名称.xlsx"}'

Input parameters

Field	Type	Required	Default value	Description
file_id	string	Yes	—	File ID (required)
new_name	string	Yes	—	New file name (required, including extension); length 1~255; forbidden characters / \ : * ? " < > |

Return

Field	Type	Description
status	string	Operation result, on success it is "success"

This interface does not return the file object; if the latest metadata is needed, you can go through "Read file information" again.

Create folder

Create a new folder under the specified directory in WeDrive.

How to call

Use the wecom-cli tool to call in the following format

wecom-cli disk folders create --json '{"folder_id": "FOLDER_ID", "folder_name": "新建文件夹"}'

Input parameters

Field	Type	Required	Default value	Description
folder_id	string	Optional	—	Target parent folder ID; can pass folder file_id or space space_id; if not provided, it defaults to creating in the root directory of the personal space
folder_name	string	Yes	—	Folder name

Return

Field	Type	Description
folder.id	string	Folder ID
folder.file_name	string	Folder name
folder.docid	string	Document ID, meaningful only for the online document type
folder.type	string	File type:folder
folder.file_size	number	File size (bytes); meaningful only when type=file is present
folder.creator_userid	string	Creator userid
folder.space_id	string	ID of the shared space it belongs to
folder.space_name	string	Name of the space it is in; returned only when you have permission for the space, appearing together with space_id appear simultaneously
folder.folder_id	string	ID of the parent folder it is in, may be folder file_id or space space_id
folder.folder_name	string	Name of the parent folder it is in; returned only when you have permission for the parent folder, appearing together with folder_id appear simultaneously
folder.create_time	string	Creation time,YYYY-MM-DD HH:mm:ss
folder.update_time	string	Last update time,YYYY-MM-DD HH:mm:ss
folder.path	string	Full folder path
folder.doc_url	string	Document open link, populated only for the online document type

Key constraints

• A filename is not file_id: when the user provides a filename/keyword, first go through disk files search to get the file_id, and do not directly concatenate the filename as file_id .
• Constraints on the source of uploaded material：upload of file_content_media and file_path : choose one of the two, one of them must be provided, and they cannot be passed at the same time.file_content_media Must be a valid media_id(prefix mc); constructing or guessing it yourself is prohibited;file_path can only be provided explicitly by the user or returned by a preceding skill as areal local file path, and fabricating it is prohibited. When neither is available, ask a follow-up question in natural language; do not scrape together a file through search/hallucination.
• Search must be bounded: after searching with one set of conditions, adjust once if necessary; if there are still no results after 2–3 rounds, stop and truthfully tell the user "not found", and ask the user to provide more accurate keywords/file type/creator. Do not endlessly switch keywords and force a search.
• Relay CLI errors verbatim: when a command returns a clear error code, truthfully inform the user and give alternative suggestions. Do not use general-purpose means such as curl / python to bypass the CLI and force completion.
• Internal IDs are not exposed：creator_userid / space_id / folder_id / file_id / docid , etc. Any ID is only used for subsequent API calls,prohibitedto be displayed directly to the user;creator_userid if creator information needs to be displayed, first use wecomcli-contact to resolve it to a name.
• Ask follow-up questions for duplicate space/folder names: when the search returns multiple spaces or folders with the same name, ask a follow-up question in natural language to let the user choose the specific target; do not randomly pick the first one or guess one.
• Missing parameters / multiple candidates / intent confirmation: use natural language follow-up questions to make the user clarify; do not guess blindly.

Result display rules

When showing list / search results to the user, strictly follow:

• Display each item one by one as a markdown unordered list; tables are prohibited—display at most 10 items.
• First line of each item: when the doc_url returned for that item is non-empty (online document), write it as a markdown link in the form - [文件名](doc_url) ;doc_url when it is empty (offline file, folder, space, etc.), write it as - 文件名, and do not fabricate a link. The secondary line may display path / update_time / readable file_size(such as 2.4 MB), separate fields with · or spaces.
• Do notdirectly display raw JSON,creator_userid / space_id / folder_id / id and other internal IDs.

Cross-skill dependencies

Dependent skill	When to trigger	What to do with the depended-on skill
wecomcli-doc	Search hit type=word / doc, the user wants to "read the content"	take the returned docid and hand it to wecom-cli doc 'contents get' to read the body (docid except those whose docid starts with a1_ / b1_ , which go through wecomcli-smartpage）
wecomcli-sheet	Search hit type=sheet(online spreadsheet), the user wants to read the content	take the returned docid and hand it to wecomcli-sheet 's corresponding read interface
wecomcli-smartsheet	Search hit type=smartsheet(smartsheet), the user wants to read the content	take the returned docid and hand it to wecomcli-smartsheet 's corresponding read interface
wecomcli-smartpage	Search hit type=smartpage(smartpage), or type=word and docid starts with a1_ / b1_ , the user wants to read the content	take the returned docid and hand it to wecomcli-smartpage 's corresponding read interface
wecomcli-doc-manage	the hit is word/sheet/smartsheet/smartpage and the user asks to change document permissions / add members / change the document name	hand it to wecomcli-doc-manage to handle; for the remaining online/offline types (file/collect/mind/flow/journal/ppt/pdf, etc.), renaming goes through this skill's rename;folder(folder) does not support renaming (see [Scope of Application]); tell the user it is not yet supported and suggest they manually operate in the WeCom client

When parameters are missing / there are multiple candidates / intent confirmation is needed, ask follow-up questions in natural language to make the user clarify.