Back to Details

wecom-cli-enterprise-wechat

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

wecom-cli Enterprise WeChat Terminal Tool

wecom-cli 企业微信终端工具

Skill by ara.so — Devtools Skills collection.
由ara.so开发的Skill工具——Devtools Skills工具集。

Overview

概述

wecom-cli
is a command-line interface for Enterprise WeChat (WeCom/企业微信) that enables developers and AI agents to interact with WeCom's API directly from the terminal. It provides comprehensive coverage of core business capabilities including documents, smart tables, messages, contacts, tasks, meetings, and calendars.
Key Features:
  • 📄 Document operations (create, read, edit, smart docs)
  • 📊 Smart table management (create, fields, records CRUD)
  • 💬 Message operations (query conversations, pull/send messages, download media)
  • 👤 Contact directory (list visible members, search by name/alias)
  • ✅ Task management (create, read, update, delete tasks)
  • 🎥 Meeting management (schedule, cancel, update attendees)
  • 📅 Calendar operations (CRUD events, manage participants, check availability)
Use Cases:
  • Enterprise (10+ users): Document and smart table automation for office efficiency
  • Personal/Small teams (≤10 users): Full access to messages, documents, calendar, meetings, and tasks
wecom-cli
是一款面向企业微信（WeCom/企业微信）的命令行界面工具，支持开发者和AI Agent直接通过终端调用企业微信API。它全面覆盖了文档、智能表格、消息、联系人、任务、会议和日历等核心业务能力。
核心特性：
  • 📄 文档操作（创建、读取、编辑、智能文档）
  • 📊 智能表格管理（创建、字段配置、记录增删改查）
  • 💬 消息操作（查询会话、拉取/发送消息、下载媒体文件）
  • 👤 联系人目录（列出可见成员、按姓名/别名搜索）
  • ✅ 任务管理（创建、读取、更新、删除任务）
  • 🎥 会议管理（预约、取消、更新参会人员）
  • 📅 日历操作（增删改查日程、管理参会者、查询空闲状态）
适用场景：
  • 企业（10人以上）：文档与智能表格自动化，提升办公效率
  • 个人/小型团队（≤10人）：全面访问消息、文档、日历、会议和任务功能

Installation

安装

Prerequisites

前置要求

  • Platform: macOS (x64/arm64), Linux (x64/arm64), Windows (x64)
  • Node.js: >= 18
  • Enterprise WeChat Account
  • Bot Credentials: Bot ID and Secret (obtain from WeCom Open Platform)
  • 支持平台：macOS（x64/arm64）、Linux（x64/arm64）、Windows（x64）
  • Node.js：版本 ≥ 18
  • 企业微信账号
  • 机器人凭证：Bot ID和Secret（从企业微信开放平台获取）

Install Steps

安装步骤

bash
undefined
bash
undefined

Install the CLI globally

全局安装CLI

npm install -g @wecom/cli
npm install -g @wecom/cli

Install CLI Skill (required)

安装CLI Skill（必需）

npx skills add WeComTeam/wecom-cli -y -g
npx skills add WeComTeam/wecom-cli -y -g

Interactive configuration (one-time setup)

交互式配置（仅需一次）

wecom-cli init

The `init` command will prompt you for:
- Bot ID
- Bot Secret
- Other optional configuration parameters
wecom-cli init

`init`命令会提示您输入以下信息：
- Bot ID
- Bot Secret
- 其他可选配置参数

Configuration

配置

Configuration is stored after running 
wecom-cli init
. Credentials should be managed securely:
bash
undefined
运行
wecom-cli init
后会保存配置信息。凭证需安全管理：
bash
undefined

Use environment variables for automation

在自动化场景中使用环境变量

export WECOM_BOT_ID="your_bot_id" export WECOM_BOT_SECRET="your_bot_secret"
undefined
export WECOM_BOT_ID="your_bot_id" export WECOM_BOT_SECRET="your_bot_secret"
undefined

Core Commands & Usage

核心命令与用法

Contact Directory

联系人目录

Get visible member list:
bash
undefined
获取可见成员列表：
bash
undefined

Get all visible contacts

获取所有可见联系人

wecom-cli contact get_userlist '{}'
wecom-cli contact get_userlist '{}'

The JSON parameter can include filters

JSON参数可包含过滤条件

wecom-cli contact get_userlist '{"dept_id": "1"}'

**Search contacts by name/alias:**

```bash
wecom-cli contact get_userlist '{"dept_id": "1"}'

**按姓名/别名搜索联系人：**

```bash

Search for a specific user

搜索特定用户

wecom-cli contact search '{"query": "张三"}'
undefined
wecom-cli contact search '{"query": "张三"}'
undefined

Messages

消息

Query conversation list:
bash
undefined
查询会话列表：
bash
undefined

Get list of conversations

获取会话列表

wecom-cli message get_conversation_list '{}'

**Pull message history:**

```bash
wecom-cli message get_conversation_list '{}'

**拉取消息历史：**

```bash

Pull messages from a conversation

从指定会话拉取消息

wecom-cli message pull_messages '{ "conversation_id": "conv_id_here", "limit": 50 }'

**Send text message:**

```bash
wecom-cli message pull_messages '{ "conversation_id": "conv_id_here", "limit": 50 }'

**发送文本消息：**

```bash

Send a text message to a user

给指定用户发送文本消息

wecom-cli message send_text '{ "userid": "user_id_here", "text": "Hello from CLI!" }'

**Download media files:**

```bash
wecom-cli message send_text '{ "userid": "user_id_here", "text": "Hello from CLI!" }'

**下载媒体文件：**

```bash

Download image/file/voice/video

下载图片/文件/语音/视频

wecom-cli message download_media '{ "media_id": "media_id_here", "media_type": "image", "output_path": "./downloads/image.jpg" }'
undefined
wecom-cli message download_media '{ "media_id": "media_id_here", "media_type": "image", "output_path": "./downloads/image.jpg" }'
undefined

Documents

文档

Create a document:
bash
undefined
创建文档：
bash
undefined

Create a new document

创建新文档

wecom-cli document create '{ "title": "Project Plan", "content": "# Project Overview\n\nThis is the project plan..." }'

**Read document content:**

```bash
wecom-cli document create '{ "title": "Project Plan", "content": "# Project Overview\n\nThis is the project plan..." }'

**读取文档内容：**

```bash

Read a document by ID

通过文档ID读取内容

wecom-cli document read '{ "doc_id": "document_id_here" }'

**Edit document:**

```bash
wecom-cli document read '{ "doc_id": "document_id_here" }'

**编辑文档：**

```bash

Update document content

更新文档内容

wecom-cli document edit '{ "doc_id": "document_id_here", "content": "Updated content here" }'

**Smart document operations:**

```bash
wecom-cli document edit '{ "doc_id": "document_id_here", "content": "Updated content here" }'

**智能文档操作：**

```bash

Create a smart document

创建智能文档

wecom-cli document create_smart '{ "title": "Smart Analysis Report", "template_id": "template_id_here" }'
wecom-cli document create_smart '{ "title": "Smart Analysis Report", "template_id": "template_id_here" }'

Read smart document

读取智能文档

wecom-cli document read_smart '{ "doc_id": "smart_doc_id_here" }'
undefined
wecom-cli document read_smart '{ "doc_id": "smart_doc_id_here" }'
undefined

Smart Tables

智能表格

Create smart table:
bash
undefined
创建智能表格：
bash
undefined

Create a new smart table

创建新智能表格

wecom-cli smartsheet create '{ "name": "Customer Database", "description": "Track customer information" }'

**Manage fields:**

```bash
wecom-cli smartsheet create '{ "name": "Customer Database", "description": "Track customer information" }'

**管理字段：**

```bash

Add a field to smart table

给智能表格添加字段

wecom-cli smartsheet add_field '{ "sheet_id": "sheet_id_here", "field_name": "Email", "field_type": "text" }'

**CRUD records:**

```bash
wecom-cli smartsheet add_field '{ "sheet_id": "sheet_id_here", "field_name": "Email", "field_type": "text" }'

**记录增删改查：**

```bash

Add a record

添加记录

wecom-cli smartsheet add_record '{ "sheet_id": "sheet_id_here", "data": { "Name": "John Doe", "Email": "john@example.com" } }'
wecom-cli smartsheet add_record '{ "sheet_id": "sheet_id_here", "data": { "Name": "John Doe", "Email": "john@example.com" } }'

Query records

查询记录

wecom-cli smartsheet get_records '{ "sheet_id": "sheet_id_here", "filter": {} }'
wecom-cli smartsheet get_records '{ "sheet_id": "sheet_id_here", "filter": {} }'

Update a record

更新记录

wecom-cli smartsheet update_record '{ "sheet_id": "sheet_id_here", "record_id": "record_id_here", "data": { "Email": "newemail@example.com" } }'
wecom-cli smartsheet update_record '{ "sheet_id": "sheet_id_here", "record_id": "record_id_here", "data": { "Email": "newemail@example.com" } }'

Delete a record

删除记录

wecom-cli smartsheet delete_record '{ "sheet_id": "sheet_id_here", "record_id": "record_id_here" }'
undefined
wecom-cli smartsheet delete_record '{ "sheet_id": "sheet_id_here", "record_id": "record_id_here" }'
undefined

Tasks (待办)

任务（待办）

Create a task:
bash
undefined
创建任务：
bash
undefined

Create a new task

创建新任务

wecom-cli task create '{ "title": "Review quarterly report", "description": "Complete review by Friday", "assignee": "user_id_here", "due_date": "2026-05-20" }'

**Read task:**

```bash
wecom-cli task create '{ "title": "Review quarterly report", "description": "Complete review by Friday", "assignee": "user_id_here", "due_date": "2026-05-20" }'

**读取任务详情：**

```bash

Get task details

获取任务详情

wecom-cli task read '{ "task_id": "task_id_here" }'

**Update task:**

```bash
wecom-cli task read '{ "task_id": "task_id_here" }'

**更新任务：**

```bash

Update task status or content

更新任务状态或内容

wecom-cli task update '{ "task_id": "task_id_here", "status": "completed" }'

**Delete task:**

```bash
wecom-cli task update '{ "task_id": "task_id_here", "status": "completed" }'

**删除任务：**

```bash

Delete a task

删除任务

wecom-cli task delete '{ "task_id": "task_id_here" }'

**Change user processing status:**

```bash
wecom-cli task delete '{ "task_id": "task_id_here" }'

**修改用户处理状态：**

```bash

Mark task as done for a user

标记用户任务为完成

wecom-cli task update_user_status '{ "task_id": "task_id_here", "userid": "user_id_here", "status": "done" }'
undefined
wecom-cli task update_user_status '{ "task_id": "task_id_here", "userid": "user_id_here", "status": "done" }'
undefined

Meetings

会议

Create scheduled meeting:
bash
undefined
创建预约会议：
bash
undefined

Schedule a new meeting

预约新会议

wecom-cli meeting create '{ "title": "Weekly Sync", "start_time": "2026-05-20T14:00:00+08:00", "end_time": "2026-05-20T15:00:00+08:00", "invitees": ["user1", "user2", "user3"] }'

**Query meeting list:**

```bash
wecom-cli meeting create '{ "title": "Weekly Sync", "start_time": "2026-05-20T14:00:00+08:00", "end_time": "2026-05-20T15:00:00+08:00", "invitees": ["user1", "user2", "user3"] }'

**查询会议列表：**

```bash

Get list of meetings

获取会议列表

wecom-cli meeting list '{ "start_date": "2026-05-01", "end_date": "2026-05-31" }'

**Get meeting details:**

```bash
wecom-cli meeting list '{ "start_date": "2026-05-01", "end_date": "2026-05-31" }'

**获取会议详情：**

```bash

Get specific meeting info

获取特定会议信息

wecom-cli meeting get '{ "meeting_id": "meeting_id_here" }'

**Update meeting attendees:**

```bash
wecom-cli meeting get '{ "meeting_id": "meeting_id_here" }'

**更新参会人员：**

```bash

Add or remove invitees

添加或移除参会者

wecom-cli meeting update_invitees '{ "meeting_id": "meeting_id_here", "add": ["user4"], "remove": ["user2"] }'

**Cancel meeting:**

```bash
wecom-cli meeting update_invitees '{ "meeting_id": "meeting_id_here", "add": ["user4"], "remove": ["user2"] }'

**取消会议：**

```bash

Cancel a scheduled meeting

取消预约会议

wecom-cli meeting cancel '{ "meeting_id": "meeting_id_here" }'
undefined
wecom-cli meeting cancel '{ "meeting_id": "meeting_id_here" }'
undefined

Calendar

日历

Create calendar event:
bash
undefined
创建日历日程：
bash
undefined

Create a new calendar event

创建新日历日程

wecom-cli calendar create '{ "summary": "Client Presentation", "start_time": "2026-05-21T10:00:00+08:00", "end_time": "2026-05-21T11:30:00+08:00", "location": "Conference Room A", "attendees": ["user1@company.com", "user2@company.com"] }'

**Read calendar event:**

```bash
wecom-cli calendar create '{ "summary": "Client Presentation", "start_time": "2026-05-21T10:00:00+08:00", "end_time": "2026-05-21T11:30:00+08:00", "location": "Conference Room A", "attendees": ["user1@company.com", "user2@company.com"] }'

**读取日历日程：**

```bash

Get event details

获取日程详情

wecom-cli calendar read '{ "event_id": "event_id_here" }'

**Update calendar event:**

```bash
wecom-cli calendar read '{ "event_id": "event_id_here" }'

**更新日历日程：**

```bash

Update event information

更新日程信息

wecom-cli calendar update '{ "event_id": "event_id_here", "summary": "Updated: Client Presentation", "location": "Conference Room B" }'

**Delete calendar event:**

```bash
wecom-cli calendar update '{ "event_id": "event_id_here", "summary": "Updated: Client Presentation", "location": "Conference Room B" }'

**删除日历日程：**

```bash

Delete an event

删除日程

wecom-cli calendar delete '{ "event_id": "event_id_here" }'

**Manage participants:**

```bash
wecom-cli calendar delete '{ "event_id": "event_id_here" }'

**管理参会者：**

```bash

Add participants to event

添加日程参会者

wecom-cli calendar add_participants '{ "event_id": "event_id_here", "attendees": ["user3@company.com"] }'
wecom-cli calendar add_participants '{ "event_id": "event_id_here", "attendees": ["user3@company.com"] }'

Remove participants

移除参会者

wecom-cli calendar remove_participants '{ "event_id": "event_id_here", "attendees": ["user2@company.com"] }'

**Check availability (free/busy):**

```bash
wecom-cli calendar remove_participants '{ "event_id": "event_id_here", "attendees": ["user2@company.com"] }'

**查询空闲状态：**

```bash

Query availability for multiple users

查询多个用户的空闲状态

wecom-cli calendar check_freebusy '{ "userids": ["user1", "user2", "user3"], "start_time": "2026-05-20T09:00:00+08:00", "end_time": "2026-05-20T18:00:00+08:00" }'
undefined
wecom-cli calendar check_freebusy '{ "userids": ["user1", "user2", "user3"], "start_time": "2026-05-20T09:00:00+08:00", "end_time": "2026-05-20T18:00:00+08:00" }'
undefined

Common Patterns

常见模式

Automation Script Example

自动化脚本示例

bash
#!/bin/bash
bash
#!/bin/bash

Automation script for daily standup meeting creation

每日站会创建自动化脚本

Uses environment variables for credentials

使用环境变量存储凭证

export WECOM_BOT_ID="${WECOM_BOT_ID}" export WECOM_BOT_SECRET="${WECOM_BOT_SECRET}"
export WECOM_BOT_ID="${WECOM_BOT_ID}" export WECOM_BOT_SECRET="${WECOM_BOT_SECRET}"

Get team members

获取团队成员

TEAM_MEMBERS=$(wecom-cli contact get_userlist '{"dept_id": "2"}')
TEAM_MEMBERS=$(wecom-cli contact get_userlist '{"dept_id": "2"}')

Extract user IDs (requires jq)

提取用户ID（需安装jq）

USERIDS=$(echo "$TEAM_MEMBERS" | jq -r '.userlist[].userid' | tr '\n' ',' | sed 's/,$//')
USERIDS=$(echo "$TEAM_MEMBERS" | jq -r '.userlist[].userid' | tr '\n' ',' | sed 's/,$//')

Create daily standup meeting

创建每日站会

TOMORROW=$(date -v+1d '+%Y-%m-%dT09:30:00+08:00') END_TIME=$(date -v+1d '+%Y-%m-%dT10:00:00+08:00')
wecom-cli meeting create "{ "title": "Daily Standup - $(date '+%Y-%m-%d')", "start_time": "$TOMORROW", "end_time": "$END_TIME", "invitees": [$(echo "$USERIDS" | sed 's/,/","/g' | sed 's/^/"/' | sed 's/$/"/')] }"
echo "✅ Daily standup meeting created"
undefined
TOMORROW=$(date -v+1d '+%Y-%m-%dT09:30:00+08:00') END_TIME=$(date -v+1d '+%Y-%m-%dT10:00:00+08:00')
wecom-cli meeting create "{ "title": "Daily Standup - $(date '+%Y-%m-%d')", "start_time": "$TOMORROW", "end_time": "$END_TIME", "invitees": [$(echo "$USERIDS" | sed 's/,/","/g' | sed 's/^/"/' | sed 's/$/"/')] }"
echo "✅ 每日站会已创建"
undefined

Task Management Workflow

任务管理工作流

bash
#!/bin/bash
bash
#!/bin/bash

Create tasks from a CSV file

从CSV文件批量创建任务

CSV format: title,description,assignee,due_date

CSV格式：标题,描述,经办人,截止日期

while IFS=, read -r title description assignee due_date; do wecom-cli task create "{ "title": "$title", "description": "$description", "assignee": "$assignee", "due_date": "$due_date" }" echo "Created task: $title" done < tasks.csv
undefined
while IFS=, read -r title description assignee due_date; do wecom-cli task create "{ "title": "$title", "description": "$description", "assignee": "$assignee", "due_date": "$due_date" }" echo "已创建任务：$title" done < tasks.csv
undefined

Document Batch Processing

文档批量处理

bash
#!/bin/bash
bash
#!/bin/bash

Create multiple project documents from templates

从模板批量创建项目文档

PROJECTS=("Project-Alpha" "Project-Beta" "Project-Gamma")
for project in "${PROJECTS[@]}"; do wecom-cli document create "{ "title": "$project - Requirements", "content": "# $project Requirements\n\n## Overview\n\nTBD" }"
wecom-cli document create "{ "title": "$project - Timeline", "content": "# $project Timeline\n\n## Milestones\n\nTBD" }"
echo "✅ Created documents for $project" done
undefined
PROJECTS=("Project-Alpha" "Project-Beta" "Project-Gamma")
for project in "${PROJECTS[@]}"; do wecom-cli document create "{ "title": "$project - Requirements", "content": "# $project Requirements\n\n## Overview\n\nTBD" }"
wecom-cli document create "{ "title": "$project - Timeline", "content": "# $project Timeline\n\n## Milestones\n\nTBD" }"
echo "✅ 已为$project创建文档" done
undefined

Smart Table Data Import

智能表格数据导入

bash
#!/bin/bash
bash
#!/bin/bash

Import JSON data into smart table

将JSON数据导入智能表格

SHEET_ID="your_sheet_id_here" DATA_FILE="customers.json"
SHEET_ID="your_sheet_id_here" DATA_FILE="customers.json"

Read JSON array and create records

读取JSON数组并创建记录

jq -c '.[]' "$DATA_FILE" | while read -r record; do wecom-cli smartsheet add_record "{ "sheet_id": "$SHEET_ID", "data": $record }" done
echo "✅ Data import completed"
undefined
jq -c '.[]' "$DATA_FILE" | while read -r record; do wecom-cli smartsheet add_record "{ "sheet_id": "$SHEET_ID", "data": $record }" done
echo "✅ 数据导入完成"
undefined

Troubleshooting

故障排查

Authentication Issues

认证问题

Problem: 
Authentication failed
error
Solution: Re-run configuration and verify credentials:
bash
undefined
问题：出现
Authentication failed
错误
解决方案：重新运行配置并验证凭证：
bash
undefined

Reinitialize configuration

重新初始化配置

wecom-cli init
wecom-cli init

Verify credentials are set

验证凭证是否已设置

echo $WECOM_BOT_ID echo $WECOM_BOT_SECRET
undefined
echo $WECOM_BOT_ID echo $WECOM_BOT_SECRET
undefined

Permission Errors

权限错误

Problem: 
Permission denied
when accessing certain APIs
Solution: Verify your bot has the required scopes and permissions in the WeCom admin console. Different capabilities (documents, messages, etc.) require different permission grants.
问题：访问部分API时出现
Permission denied
错误
解决方案：在企业微信管理后台验证机器人是否拥有所需的权限范围。不同功能（文档、消息等）需要不同的权限授权。

JSON Parsing Errors

JSON解析错误

Problem: 
Invalid JSON parameter
error
Solution: Ensure JSON is properly escaped in shell commands:
bash
undefined
问题：出现
Invalid JSON parameter
错误
解决方案：确保在Shell命令中正确格式化JSON：
bash
undefined

Correct: Use single quotes around JSON

正确写法：用单引号包裹JSON

wecom-cli task create '{"title": "My Task"}'
wecom-cli task create '{"title": "My Task"}'

Incorrect: Double quotes need escaping

错误写法：双引号需要转义

wecom-cli task create "{"title": "My Task"}"
undefined
wecom-cli task create "{"title": "My Task"}"
undefined

Rate Limiting

频率限制

Problem: 
Rate limit exceeded
errors
Solution: Implement retry logic with exponential backoff:
bash
#!/bin/bash

retry_command() {
  local max_attempts=3
  local attempt=1
  local delay=2
  
  while [ $attempt -le $max_attempts ]; do
    if $@; then
      return 0
    else
      echo "Attempt $attempt failed. Retrying in ${delay}s..."
      sleep $delay
      delay=$((delay * 2))
      attempt=$((attempt + 1))
    fi
  done
  
  return 1
}
问题：出现
Rate limit exceeded
错误
解决方案：实现带指数退避的重试逻辑：
bash
#!/bin/bash

retry_command() {
  local max_attempts=3
  local attempt=1
  local delay=2
  
  while [ $attempt -le $max_attempts ]; do
    if $@; then
      return 0
    else
      echo "第$attempt次尝试失败，${delay}秒后重试..."
      sleep $delay
      delay=$((delay * 2))
      attempt=$((attempt + 1))
    fi
  done
  
  return 1
}

Usage

使用示例

retry_command wecom-cli message send_text '{"userid": "user1", "text": "Hello"}'
undefined
retry_command wecom-cli message send_text '{"userid": "user1", "text": "Hello"}'
undefined

Debug Mode

调试模式

Enable verbose logging for troubleshooting:
bash
undefined
启用详细日志用于故障排查：
bash
undefined

Set debug environment variable

设置调试环境变量

export WECOM_CLI_DEBUG=1
export WECOM_CLI_DEBUG=1

Run command with debug output

运行命令并查看调试输出

wecom-cli contact get_userlist '{}'
undefined
wecom-cli contact get_userlist '{}'
undefined

Best Practices

最佳实践

  1. Use environment variables for credentials in CI/CD and automation scripts
  2. Validate JSON before passing to commands (use 
    jq
    or similar tools)
  3. Handle errors gracefully in scripts with proper exit codes
  4. Rate limit your requests when performing batch operations
  5. Store media files with organized naming conventions when downloading
  6. Version control your automation scripts alongside your project
  7. Test with small datasets before running large batch operations
  1. 在CI/CD和自动化脚本中使用环境变量存储凭证
  2. 在传入命令前验证JSON格式（使用
    jq
    等工具）
  3. 在脚本中优雅处理错误，设置正确的退出码
  4. 执行批量操作时控制请求频率，避免触发限制
  5. 下载媒体文件时使用规范的命名规则，便于管理
  6. 将自动化脚本与项目一起进行版本控制
  7. 在执行大规模批量操作前，先用小数据集测试

Additional Resources

更多资源