WeCom Smart Sheet Management

wecom-cli
is a command-line program provided by WeCom. All operations are completed by executing
wecom-cli
commands.

Manage the structure (sub-sheets, fields/columns) and data (records) of WeCom Smart Sheets. All interfaces support locating documents by choosing either

docid

url

Calling Method

Call via

wecom-cli

, category is

doc

bash

wecom-cli doc <tool_name> '<json_params>'

Return Format Description

All interfaces return JSON objects containing the following public fields:

Field	Type	Description
`errcode`	integer	Return code, `0` indicates success, non- `0` indicates failure
`errmsg`	string	Error message, `"ok"` when successful

When

errcode

is not

, it means the interface call failed. You can retry once; if it still fails, display

errcode

and

errmsg

to the user.

I. Smart Sheet Structure Management

smartsheet_get_sheet

Query all sub-sheet information in the document, returning sheet_id, title, type, etc.

bash

wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'

smartsheet_add_sheet

Add an empty sub-sheet. The new sub-sheet contains no views, records or fields, which need to be supplemented via other interfaces.

bash

wecom-cli doc smartsheet_add_sheet '{"docid": "DOCID", "properties": {"title": "New Sub-sheet"}}'

Note: A newly created Smart Sheet document contains one sub-sheet by default. Only call this when multiple sub-sheets are needed.

smartsheet_update_sheet

Modify the title of a sub-sheet. Need to provide sheet_id and new title.

bash

wecom-cli doc smartsheet_update_sheet '{"docid": "DOCID", "properties":{"sheet_id":"SHEET_ID", "title":"New Sub-sheet"}}'

smartsheet_delete_sheet

Permanently delete a sub-sheet, this operation is irreversible.

bash

wecom-cli doc smartsheet_delete_sheet '{"docid": "DOCID", "sheet_id": "SHEETID"}'

smartsheet_get_fields

Query all field information of a sub-sheet, returning field_id, field_title, field_type.

bash

wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'

smartsheet_add_fields

Add one or more fields to a sub-sheet. A single sub-sheet can have a maximum of 150 fields.

bash

wecom-cli doc smartsheet_add_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_title": "Task Name", "field_type": "FIELD_TYPE_TEXT"}]}'

Before adding fields, please refer to all field types and definitions Field Type Reference.

smartsheet_update_fields

Update field titles. Only the name can be changed, not the type (field_type must be the original type). field_title cannot be updated to its original value.

bash

wecom-cli doc smartsheet_update_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_id": "FIELDID", "field_title": "New Title", "field_type": "FIELD_TYPE_TEXT"}]}'

smartsheet_delete_fields

Delete one or more fields, this operation is irreversible. field_id can be obtained via

smartsheet_get_fields

bash

wecom-cli doc smartsheet_delete_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "field_ids": ["FIELDID"]}'

II. Smart Sheet Data Management

smartsheet_get_records

Query all records of a sub-sheet.

Via docid:

bash

wecom-cli doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'

Or via URL:

bash

wecom-cli doc smartsheet_get_records '{"url": "https://doc.weixin.qq.com/smartsheet/xxx", "sheet_id": "SHEETID"}'

See API Details.

smartsheet_add_records Add one or more records (without images or files)

Add one or more records, it is recommended to add within 500 rows at a time.

Before calling, you must understand the field types of the target sheet (via

smartsheet_get_fields

), focusing on

field_type

. For single-select/multi-select (Option) fields, note to match the

id

of existing options.

bash

wecom-cli doc smartsheet_add_records '{"docid": "DOCID", "sheet_id": "SHEETID", "records": [{"values": {"Task Name": [{"type": "text", "text": "Complete Requirements Document"}], "Priority": [{"text": "High"}]}}]}'

Refer to Cell Value Format Reference for the value format of each field type.

+smartsheet_add_records_auto_file Add one or more records (with images or files)

Add one or more records, it is recommended to add within 500 rows at a time. Different from

smartsheet_add_records

, this interface supports passing in images and files via local paths. For adding records with images or files, please use this interface. After being passed to the backend, the backend will automatically store and convert them to image_url.

bash

wecom-cli doc +smartsheet_add_records_auto_file '{"docid":"DOCID","sheet_id":"SHEETID","records":[{"values":{"Image":[{"image_path":"/path/to/image.jpg"}],"File":[{"file_path":"/path/to/file.txt"}]}}]}'

smartsheet_update_records Update records (without images or files)

Update one or more records, it is recommended to update within 500 rows at a time. Need to provide record_id (obtained via

smartsheet_get_records

). Supports specifying the key of values to use field title or field ID via

key_type

```
CELL_VALUE_KEY_TYPE_FIELD_TITLE
```
: key is field title
```
CELL_VALUE_KEY_TYPE_FIELD_ID
```
: key is field ID

bash

wecom-cli doc smartsheet_update_records '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"Task Name": [{"type": "text", "text": "Updated Content"}]}}]}'

Note: Fields of creation time, last edit time, creator, and last editor cannot be updated.

+smartsheet_update_records_auto_file Update records (update image or file fields)

Update one or more records, it is recommended to update within 500 rows at a time. Different from

smartsheet_update_records

, this interface supports passing in images and files via local paths. For updating images or files in records, please use this interface. After being passed to the backend, the backend will automatically store and convert them to image_url.

bash

wecom-cli doc +smartsheet_update_records_auto_file '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE", "records": [{"record_id": "RECORDID", "values": {"values":{"Image":[{"image_path":"/path/to/image.jpg"}],"File":[{"file_path":"/path/to/file.txt"}]}}}]}'

smartsheet_delete_records

Delete one or more records, must delete within 500 rows at a time. This operation is irreversible. record_id is obtained via

smartsheet_get_records

. Express Smart Sheet does not support this interface.

bash

wecom-cli doc smartsheet_delete_records '{"docid": "DOCID", "sheet_id": "SHEETID", "record_ids": ["RECORDID1", "RECORDID2"]}'

Typical Workflows

Smart Sheet Structure Operations

Understand sheet structure →

bash

wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'

→

bash

wecom-cli doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'

Create sheet structure →
```
smartsheet_add_sheet
```
to add sub-sheet →
```
smartsheet_add_fields
```
to define columns
Modify sheet structure →
```
smartsheet_update_fields
```
to rename columns /
```
smartsheet_delete_fields
```
to delete columns

Smart Sheet Data Operations

Read data →

bash

wecom-cli doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}'

Write data → First use
```
smartsheet_get_fields
```
to understand column types → If involving member (USER) fields, first find the userid via
```
get_userlist
```
of
```
wecomcli-contact
```
→ Use
```
smartsheet_add_records
```
to write
Update data → First use
```
smartsheet_get_records
```
to get record_id → If involving member (USER) fields, first find the userid via
```
get_userlist
```
of
```
wecomcli-contact
```
→ Use
```
smartsheet_update_records
```
to update
Delete data → First use
```
smartsheet_get_records
```
to confirm record_id → Use
```
smartsheet_delete_records
```
to delete

Note: Member (USER) type fields require filling in
user_id
, not directly using the name. You must first find the corresponding
userid
by name via the
get_userlist
interface of the
wecomcli-contact
skill before using it.

wecomcli-smartsheet

NPX Install

Tags

SKILL.md Content (Chinese)

WeCom Smart Sheet Management

Calling Method

Return Format Description

I. Smart Sheet Structure Management

smartsheet_get_sheet

smartsheet_add_sheet

smartsheet_update_sheet

smartsheet_delete_sheet

smartsheet_get_fields

smartsheet_add_fields

smartsheet_update_fields

smartsheet_delete_fields

II. Smart Sheet Data Management

smartsheet_get_records

smartsheet_add_records Add one or more records (without images or files)

+smartsheet_add_records_auto_file Add one or more records (with images or files)

smartsheet_update_records Update records (without images or files)

+smartsheet_update_records_auto_file Update records (update image or file fields)

smartsheet_delete_records

Typical Workflows

Smart Sheet Structure Operations

Smart Sheet Data Operations