weixin-mp-cli

English | 中文

weixin-mp-cli 是一个基于 TypeScript 的微信公众号官方 API 命令行工具。当前支持基础支持中的 access_token、图文消息内图片、草稿箱、发布能力、永久素材、临时素材和基于环境变量的多账号凭据，后续可以继续扩展菜单、用户等公众号能力。

安装

全局安装：

npm install -g weixin-mp-cli

安装后查看帮助：

weixin-mp --help

查看已安装的 CLI 版本：

weixin-mp --version

全局安装后，如需安装可选 Agent skill：

weixin-mp install-skill

默认会把内置 skill 复制到：

~/.agents/skills/weixin-mp-cli-skills

需要自定义 skills 根目录时：

weixin-mp install-skill --target ~/.agents/skills

本地开发：

npm install
npm run build
npm link

基础支持

CLI 支持微信公众号的两类常见账号：订阅号和服务号。发布文章相关命令对两类账号都使用官方草稿箱和发布能力接口；命令是否成功取决于账号认证状态、接口权限和微信公众平台 IP 白名单配置。

推荐使用环境变量配置公众号凭据：

export WXMP_APP_ID="你的 AppID"
export WXMP_APP_SECRET="你的 AppSecret"

持久化默认账号到当前用户的 shell 配置：

export WXMP_APP_SECRET="你的 AppSecret"
weixin-mp env:set --app-id "你的 AppID"
source ~/.bashrc

access_token 默认缓存到以下文件：

~/.weixin-mp-cli-cache.json

可以通过 --cache-file 或 WXMP_CACHE_FILE 修改缓存位置。

多账号环境变量

通过分组环境变量提供不同账号的凭据。账号名会转成大写，并把非字母数字字符替换为 _，所以 service-1 对应 WXMP_SERVICE_1_APP_ID 和 WXMP_SERVICE_1_APP_SECRET：

export WXMP_SERVICE_1_APP_ID="你的 AppID"
export WXMP_SERVICE_1_APP_SECRET="你的 AppSecret"

weixin-mp token --account service-1
weixin-mp draft:add --account service-1 --file examples/article.json
weixin-mp publish:submit --account service-1 --media-id MEDIA_ID

持久化分组账号到当前用户的 shell 配置：

export WXMP_SERVICE_1_APP_SECRET="你的 AppSecret"
weixin-mp env:set --account service-1 --app-id "你的 AppID"
source ~/.bashrc

access_token

获取并缓存 access_token：

weixin-mp token

强制刷新 access_token：

weixin-mp token --force-refresh

图文消息内图片

上传文章正文图片，返回的 URL 可放入文章 HTML：

weixin-mp upload-image --file ./image.png

草稿箱

新增草稿：

weixin-mp draft:add --file examples/article.json

查询草稿总数：

weixin-mp draft:count

分页查询草稿列表：

weixin-mp draft:list --offset 0 --count 20

不返回正文内容，适合只看列表：

weixin-mp draft:list --offset 0 --count 20 --no-content

更新草稿中的某一篇文章。--index 0 表示第一篇：

weixin-mp draft:update --media-id MEDIA_ID --index 0 --file examples/article.json

删除草稿：

weixin-mp draft:delete --media-id MEDIA_ID

发布能力

提交草稿发布：

weixin-mp publish:submit --media-id MEDIA_ID

查询发布任务状态：

weixin-mp publish:status --publish-id PUBLISH_ID

分页查询已成功发布的文章：

weixin-mp publish:list --offset 0 --count 20

不返回正文内容，适合只看列表：

weixin-mp publish:list --offset 0 --count 20 --no-content

查询已发布文章详情：

weixin-mp publish:get --article-id ARTICLE_ID

删除已发布文章：

weixin-mp publish:delete --article-id ARTICLE_ID

删除多图文中的指定文章。--index 1 表示第一篇；不传 --index 时按官方接口语义删除整篇图文：

weixin-mp publish:delete --article-id ARTICLE_ID --index 1

永久素材

查询永久素材数量：

weixin-mp material:count

分页查询永久素材列表。列表类型支持 image、voice、video、news：

weixin-mp material:list --type image --offset 0 --count 20

根据 media_id 获取永久素材。图文和视频素材通常返回 JSON：

weixin-mp material:get --media-id MEDIA_ID

图片和语音素材可能返回二进制内容，需要用 --output 保存：

weixin-mp material:get --media-id MEDIA_ID --output ./material.bin

删除永久素材：

weixin-mp material:delete --media-id MEDIA_ID

上传永久图片、语音或缩略图素材：

weixin-mp material:add --type image --file image.png
weixin-mp material:add --type voice --file audio.mp3
weixin-mp material:add --type thumb --file thumb.jpg

上传永久视频素材：

weixin-mp material:add --type video --file video.mp4 --title "视频标题" --introduction "视频简介"

临时素材

临时素材会在微信侧保存 3 天。官方 API 支持上传和获取，但不提供临时素材的列表、删除或统计接口。

上传临时素材。类型支持 image、voice、video、thumb：

weixin-mp media:upload --type image --file image.png
weixin-mp media:upload --type voice --file audio.mp3
weixin-mp media:upload --type video --file video.mp4
weixin-mp media:upload --type thumb --file thumb.jpg

下载临时素材到本地文件：

weixin-mp media:get --media-id MEDIA_ID --output ./media.bin

下载通过 JSSDK 上传的高清临时语音素材：

weixin-mp media:get-jssdk --media-id MEDIA_ID --output ./voice.speex

Agent Skill

npm 包内包含一个可选 Agent skill，供用户让 Agent 按统一方式操作此 CLI。

npm install -g 时不会自动安装 skill，需要用户显式执行：

weixin-mp install-skill

该命令不需要微信公众号凭据，只会把包内置的 skills/weixin-mp-cli-skills 目录复制到目标 skills 根目录。

文章 JSON 格式

示例文件见 examples/article.json。

新增草稿时，JSON 结构如下：

{
  "articles": [
    {
      "title": "示例文章标题",
      "author": "作者",
      "digest": "文章摘要",
      "content": "<p>正文 HTML</p>",
      "content_source_url": "https://example.com/original",
      "thumb_media_id": "永久封面素材 media_id",
      "need_open_comment": 0,
      "only_fans_can_comment": 0
    }
  ]
}

注意事项：

• 普通图文的 thumb_media_id 必须是永久封面素材的 media_id。
• 正文 content 中的图片需要先通过 weixin-mp upload-image 上传，并使用返回的微信图片 URL。
• publish:submit 返回 publish_id，后续用 publish:status 查询发布任务状态。
• publish:list 返回已成功发布的文章，里面会包含 article_id，后续可用于详情查询或删除。

分发安装

发布到 npm 后，其他电脑可以直接安装：

npm install -g weixin-mp-cli

如果不发布到 npm，也可以打包分发：

npm run build
npm pack

把生成的 .tgz 文件复制到其他电脑后安装：

npm install -g ./weixin-mp-cli-0.1.13.tgz

开发脚本

npm run typecheck
npm run build