wecomcli-sheet

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.

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

WeCom online spreadsheet management

Resource-type skill, responsible for the creation, import, content reading and writing, and sub-sheet management of online spreadsheets (sheet).

Scope of application

Applicable

• Create / import WeCom online spreadsheets
• Read / modify / append online spreadsheet content
• Add / delete online spreadsheet sub-sheets

Not applicable

• Search documents / modify document permissions / rename / add members → use instead wecomcli-doc-manage
• The link provided by the user is https://doc.weixin.qq.com/smartsheet/... → use instead wecomcli-smartsheet
• If the encountered docid starts with s3 (in the form s3_xxxx) → use instead wecomcli-smartsheet

Interface routing table

Hard rule: the second column is the references/xxx.md link. After matching this row, first read the corresponding references file, then construct the command.

User intent	Reference location
Create online spreadsheet	See "Create online spreadsheet" below
Import local CSV / Excel file as a WeCom online spreadsheet	See "Import online spreadsheet" below
Read online spreadsheet basic information and sub-sheet list	See "Read online spreadsheet" below
Read online spreadsheet sub-sheet data	references/sheet-ranges-get.md
Modify the content of a specified range in an online spreadsheet	references/sheet-contents-update.md
Append a row of data at the end of an online spreadsheet	references/sheet-rows-append.md
Add an online spreadsheet sub-worksheet	references/sheet-subsheets-add.md
Delete an online spreadsheet sub-worksheet	references/sheet-subsheets-delete.md

Interface details

Create online spreadsheet

Create a new WeCom online spreadsheet from scratch: blank, or with initial data (two-dimensional spreadsheet data).This interface does not accept any file path parameters——"create/import with a local file" goes through "Import online spreadsheet".

Call method

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

wecom-cli sheet create --json '<JSON 参数>'

Parameters

Field	Type	Required	Default value	Meaning
doc_name	string	Yes	—	Spreadsheet title
grid_data	object	No	—	Default sub-sheet initialization data; for the substructure, see below

grid_data object structure:

Subfield	Type	Required	Default value	Meaning
start_row / start_column	int	No	0	Start row / column number, starting from 0
rows	array	No	—	Data for each row; each item values is a cell array
rows[].values[].cell_value	object	No	—	Cell value, see "cell_value Type Selection" below
rows[].values[].data_type	string	No	—	Enum:TEXT / NUMBER / LINK / FORMULA

cell_value Type Selection

Hard rule: after selecting the cell_value form, you must simultaneously set the sibling data_type to the corresponding value in the table below.

Form	Corresponding data_type	Structure	Applicable scenario
text	TEXT	{"text": "<纯文本>"}	Plain text content (such as names, descriptions, labels, ID strings, etc.)
number	NUMBER	{"number": 123.45}	Numeric values, used for amounts, quantities, ratios, and other data that needs to participate in formula calculations or aggregation; the value is a JSON number type, without quotes
formula	FORMULA	{"formula": "=SUM(A1,A2)"}	Any formula starting with = , including =SUM(...)、=A1+B1、=IF(...)、=VLOOKUP(...) , etc.
link	LINK	{"link": {"url": "<URL>", "text": "<显示文本>"}}	Hyperlink

Return

Field	Type	Description
docid	string	New spreadsheet ID
url	string	Spreadsheet access link

Usage rules

• When to use import instead of this API: when the user mentions a specific file path, or explicitly says "import / build with this file", always use "Import Online Spreadsheet".

Import Online Spreadsheet

Import a local file (.csv / .xls / .xlsx) as a WeCom online spreadsheet.

Invocation method

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

wecom-cli sheet import --json '<JSON 参数>'

Parameters

Field	Type	Required	Default value	Semantics
file_name	string	Yes	—	Binary file name (including extension), used for business logic to determine the source file type
file_path	string	Yes	—	Local absolute path of the source file
passwd	string	No	—	Office file encryption password (if any)

Return

Field	Type	Description
docid	string	Spreadsheet ID after import is complete
url	string	Access link after import is complete
task_status	string	Task status enum, such as succ success

Read Online Spreadsheet

Based on docid readOnline Spreadsheet's basic information, including worksheet list, document name, and access link. The sheet * of all subsequent sheet_id APIs are taken from the sheets[] returned by this API.

Invocation method

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

wecom-cli sheet get --json '<JSON 参数>'

Parameters

Field	Type	Required	Default value	Semantics
docid	string	Yes	—	Online spreadsheet ID

Return

Field	Type	Description
sheets	array	Worksheet list; each item contains sheet_id / title / row_count / column_count / data_range and other basic information
url	string	Document access link
name	string	Document name

Usage rules

• After obtaining sheet_id ,continuing to read sub-sheet data is another API, the command string, parameter names, whether pagination is used, etc. do not appear in this section,mustfirst use read the tool to read references/sheet-ranges-get.md, then construct the command based on it.

Cross-skill dependencies

Dependent skills	Typical collaboration scenarios	Data flow
wecomcli-doc-manage	The user only provides a table name/keyword and needs to search to obtain the docid before reading/writing the table; or requires file-level operations (rename, permissions, etc.)	wecomcli-doc-manage 's "Search Documents" interface → returns docid → this skill's read/modify/append interfaces

Required parameter missing / docid multiple candidates / ambiguous scenarios such as new vs import; use concise natural language to ask only about the missing or ambiguous information; when there are candidate items, list them in the text for the user to choose, and do not guess on your own.

docid Usage rules

docidCLI only. When finally presenting to the user, do not show docid, but instead use the document URL:

[doc_name](doc_url)

docid is the unique identifier of the document and must be provided when calling any document content operation skill. Do not fabricate docid. Obtain it according to the following priority:

1. Extract from the document link (preferred): when the user provides a WeCom document URL, parse it directly from the URL. The URL format is https://doc.weixin.qq.com/<type>/<docid>?scode=..., take the part after /<type>/ and before? as the docid.
2. Obtain via document search (alternative): when the user only provides the document name or keyword and no link, first call wecomcli-doc-manage to search documents, and take from the returned results docid。
3. Provided directly by the user: the user explicitly provided the complete docid, which can be used directly without further extraction or search.