wecomcli-smartsheet

WeCom Smart Sheet Management

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

Resource skill for creating and managing smart sheets (/smartsheet/*, doc_type=10): structure (sub-sheets, fields/columns) and data (records). All interfaces support locating documents by either docid or url.

Invocation

Invoke via wecom-cli with category doc:

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

For smart sheet interfaces, pass either docid or url. Examples below use docid; URL usage is analogous.

Response Format

All interfaces return a JSON object with common fields:

Field	Type	Description
errcode	integer	Return code, 0 for success, non-zero for failure
errmsg	string	Error message, "ok" on success

If errcode is non-zero, retry once; if still failing, show errcode and errmsg to the user.

Special Error Codes

errcode	errmsg	Meaning	Handling
851002	incompatible doc type	Document type does not match the interface	Confirm target URL is /smartsheet/*; if not, switch to the appropriate skill

Interface Routing Table

Hard rule: If the second column is a references/xxx.md link, first read the corresponding references file, then construct the command. Before writing/reading records, use smartsheet_get_sheet to get the target sub-sheet's sheet_id, and smartsheet_get_fields to understand field types.

User Intent	Reference
Create smart sheet from scratch (blank)	See "Create Smart Sheet" below
Query all sub-sheets in document	See "Query Sub-sheets" below
Add / rename / delete sub-sheet	See "Sub-sheet Management" below
Query sub-sheet fields/columns	See "Query Fields" below
Add fields/columns	references/smartsheet-field-types.md
Rename / delete fields	See "Field Management" below
Query sub-sheet records	references/smartsheet-get-records.md
Add records / update records	references/smartsheet-cell-value-formats.md
Delete records	See "Delete Records" below

---

1. Create Smart Sheet

Create Smart Sheet

Create a blank WeCom smart sheet (doc_type=10). Returns docid and url on success.

Command

wecom-cli doc create_doc '<JSON params>'

Parameters

Parameter	Type	Required	Default	Description
doc_type	int	Yes	—	Must be 10 (smart sheet)
doc_name	string	Yes	—	Sheet title, max 255 characters, truncated if exceeded

Notes

• A newly created smart sheet already contains one default sub-sheet. Use smartsheet_get_sheet to get its sheet_id. Only call smartsheet_add_sheet if you need additional sub-sheets.
• docid is returned only at creation and cannot be retrieved later; save it.

---

2. Smart Sheet Structure Management

Query Sub-sheets

Query all sub-sheets in a document, returning sheet_id, title, type, etc.

# By docid
wecom-cli doc smartsheet_get_sheet '{"docid": "DOCID"}'
# By url
wecom-cli doc smartsheet_get_sheet '{"url": "https://doc.weixin.qq.com/smartsheet/xxx"}'

Sub-sheet Management

Add Sub-sheet — Add an empty sub-sheet. New sub-sheets have no views, records, or fields; add them via other interfaces.

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

Note: A new smart sheet already has one default sub-sheet; only call this if you need more.

Rename Sub-sheet — Requires sheet_id and new title.

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

Delete Sub-sheet — Permanently deletes a sub-sheet. Irreversible.

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

Query Fields

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

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

Field Management

Add Fields — Add one or more fields to a sub-sheet. Max 150 fields per sub-sheet.

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

Before adding fields, refer to all field types and definitions in Field Types Reference.

Note: If this is the first time creating a table and you call this method to add fields, you must ensure the following steps are completed, otherwise an unwanted default column will appear:

1. Call smartsheet_get_fields to check existing fields (new sub-sheets have a default text field)
2. Call smartsheet_update_fields to rename that default field to your first desired field name, then pass only the remaining fields (excluding the first one) in this interface.

Update Field Title — Can only rename, not change type (field_type must be the original type). field_title cannot be updated to the same value.

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

Delete Fields — Delete one or more columns. Irreversible. Get field_id via smartsheet_get_fields.

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

---

3. Smart Sheet Data Management

Query Records

Query all records in a sub-sheet.

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

See API Details.

Add Records (without images or files)

Add one or more rows. Recommended max 500 rows per call.

Before calling, understand the target table's field types via smartsheet_get_fields, especially field_type. For single/multi-select (Option) fields, match existing option ids.

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

See Cell Value Format Reference for value formats per field type.

Add Records (with images or files)

Add one or more rows with local image/file paths. Recommended max 500 rows per call. Unlike smartsheet_add_records, this supports local paths for images and files. The backend stores them and converts to image_url.

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"}]}}]}'

Update Records (without images or files)

Update one or more rows. Recommended max 500 rows per call. Requires record_id (from smartsheet_get_records). Supports key_type to specify whether values keys use field title or field ID:

• CELL_VALUE_KEY_TYPE_FIELD_TITLE: keys are field titles
• CELL_VALUE_KEY_TYPE_FIELD_ID: keys are field IDs

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: Creation time, last edit time, creator, and last editor fields cannot be updated.

Update Records (update image or file fields)

Update one or more rows with local image/file paths. Recommended max 500 rows per call. Unlike smartsheet_update_records, this supports local paths for images and files. The backend stores them and converts to image_url.

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": {"Image":[{"image_path":"/path/to/image.jpg"}],"File":[{"file_path":"/path/to/file.txt"}]}}]}'

Delete Records

Delete one or more rows. Max 500 rows per call. Irreversible. Get record_id via smartsheet_get_records. Not supported for lite smart sheets.

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

---

Typical Workflows

Create and Set Up Table Structure

1. Create smart sheet →

wecom-cli doc create_doc '{"doc_type": 10, "doc_name": "Project Task Table"}'

, save returned docid.
2. Understand default sub-sheet → smartsheet_get_sheet to get default sub-sheet's sheet_id → smartsheet_get_fields to see default fields.
3. Set up columns → First smartsheet_update_fields to rename default field, then smartsheet_add_fields to add remaining fields.

Smart Sheet Structure Operations

1. Understand structure →

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

→

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

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

Smart Sheet Data Operations

1. Read data →

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

2. Write data → First smartsheet_get_fields to understand column types → If USER fields involved, use wecomcli-contact's get_userlist to find userid → smartsheet_add_records to write
3. Update data → First smartsheet_get_records to get record_id → If USER fields involved, use wecomcli-contact's get_userlist to find userid → smartsheet_update_records to update
4. Delete data → First smartsheet_get_records to confirm record_id → smartsheet_delete_records to delete

Cross-Skill Dependencies

Dependent Skill	Typical Collaboration Scenario	Data Flow
wecomcli-contact	USER type fields require user_id, not name	get_userlist to find userid by name → this skill writes
wecomcli-msg	User wants to send smart sheet link to someone/group	This skill returns url after creation → wecomcli-msg sends link

Note: USER type fields require user_id, not name. Use wecomcli-contact skill's get_userlist interface to find the corresponding userid by name before using it.