命令参考

全局 flag

适用于所有子命令：

Flag	含义	默认值
`-o, --output {json\|table}`	输出格式	`table`
`--api-key <key>`	单次覆盖 Feed 密钥（优先级：环境变量 `MP2RSS_FEED_KEY` > 配置文件）	—
`--api-url <url>`	单次覆盖 API 地址（优先级：`--api-url` > `MP2RSS_API_URL` > 配置 > 默认值）	`https://mp2rss.bugcode.dev`
`-h, --help`	查看帮助	—
`--version`	查看版本	—

JSON 模式错误也走 stdout

所有命令在 -o json 模式下，错误也以 JSON 写入 stdout（不是 stderr），便于 jq 等工具统一处理。错误结构：

json

{ "error": { "message": "Feed key invalid", "code": 401 } }

退出码

码	含义
`0`	成功
`1`	通用错误（未分类，例如网络异常）
`2`	参数错误（缺失、格式不正确）
`3`	鉴权失败（Feed 密钥缺失或无效）
`4`	资源不存在（如 mpId 找不到）
`5`	数据源不可用

`mp2rss auth`

鉴权相关子命令，详细使用见登录。

`mp2rss auth login`

完成首次登录，把 Feed 密钥写入 ~/.mp2rss/config.json。

bash

mp2rss auth login                       # 默认：浏览器 + loopback
mp2rss auth login -k <feed-key>         # 直接传入
mp2rss auth login --feed-key <feed-key> # 同上长写法
mp2rss auth login --no-browser          # 远程 / 无浏览器

Flag	含义
`-k, --feed-key <key>`	跳过浏览器直接落盘
`--no-browser`	不打开浏览器、不起 loopback，由用户手动粘贴密钥

`mp2rss auth logout`

清空配置中的 feed_key，保留 api_url。

bash

mp2rss auth logout

`mp2rss auth status`

显示登录状态、API 地址、Feed 密钥掩码、最近一次成功调用时间。

bash

mp2rss auth status
mp2rss auth status -o json

`mp2rss mp`

公众号订阅与文章相关子命令。X 信息源对应子命令见下方 mp2rss x。

`mp2rss mp list`

列出当前账户下的订阅。

bash

mp2rss mp list
mp2rss mp list -q 公众号                     # 按名称模糊搜索
mp2rss mp list -p 2 --page-size 20           # 分页
mp2rss mp list -o json | jq '.items[].mpName'

Flag	默认	含义
`-q, --query <kw>`	—	按公众号名称模糊匹配
`-p, --page <n>`	`1`	页码
`--page-size <n>`	`20`	每页记录数（最大 50）

HTTP 映射：GET /open-api/subscriptions

表格输出示例：

MP_ID    公众号             最新文章               订阅时间
2234567  公众号 A          2026-05-13 09:14      2026-04-20 17:31
2238910  公众号 B          -                     2026-05-01 08:02

JSON 输出示例：

json

{
  "items": [
    {
      "mpId": 2234567,
      "mpName": "公众号 A",
      "mpAvatarUrl": null,
      "createdAt": 1776553200000,
      "mpLastArticleAt": 1776854096000
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

`mp2rss mp search`

mp list -q <keyword> 的语法糖。

bash

mp2rss mp search 公众号
mp2rss mp search 公众号 -p 2

Flag	默认	含义
`-p, --page <n>`	`1`	页码
`--page-size <n>`	`20`	每页记录数

HTTP 映射：GET /open-api/subscriptions?q=<keyword>

`mp2rss mp subscribe`

通过任意一篇该公众号的文章链接发起订阅。

bash

mp2rss mp subscribe https://mp.weixin.qq.com/s/xxxxxxxxxx

HTTP 映射：POST /open-api/subscriptions，body { "articleUrl": "<...>" }，成功返回 204。

表格输出：

✓ 订阅成功

JSON 输出：

json

{ "ok": true, "articleUrl": "https://mp.weixin.qq.com/s/xxxxxxxxxx" }

`mp2rss mp remove`

取消订阅一个公众号。默认会要求交互确认，加 -y/--yes 跳过确认。

bash

mp2rss mp remove 2234567
mp2rss mp remove 2234567 --yes        # 跳过确认（脚本场景）
mp2rss mp remove 2234567 -y           # 同上短写法

Flag	默认	含义
`-y, --yes`	`false`	跳过交互确认

HTTP 映射：DELETE /open-api/subscriptions/{mpId}，成功返回 204。

表格输出：

✓ 已取消订阅 mpId=2234567

JSON 输出：

json

{ "ok": true, "mpId": 2234567 }

`mp2rss mp articles`

查询某公众号的历史文章列表。

bash

mp2rss mp articles 2234567
mp2rss mp articles 2234567 -p 2 --page-size 100
mp2rss mp articles 2234567 -o json | jq '.items[].title'

Flag	默认	含义
`-p, --page <n>`	`1`	页码
`--page-size <n>`	`100`	每页记录数

HTTP 映射：GET /open-api/subscriptions/{mpId}/articles

表格输出示例：

发布时间             标题                                    链接
2026-05-13 09:14    示例文章标题 A                          https://mp.weixin.qq.com/s/aaa
2026-05-10 18:02    示例文章标题 B（标题超长会被截断…）       https://mp.weixin.qq.com/s/bbb

JSON 输出示例：

json

{
  "items": [
    {
      "mpId": 2234567,
      "articleId": "a1",
      "title": "示例文章标题 A",
      "summary": "文章摘要",
      "coverImageUrl": null,
      "originalUrl": "https://mp.weixin.qq.com/s/aaa",
      "contentMarkdown": "# Hi\n\n这是一篇测试文章。",
      "publishedAt": 1776854096000,
      "updatedAt": 1776854100000
    }
  ]
}

TIP

mp articles 响应只含 items，没有 total / page / pageSize。如果需要分页元信息，可通过 --page / --page-size 翻页并自行判断是否到达末页（items 数量小于 --page-size 即末页）。

`mp2rss x`

X（Twitter）信息源相关子命令。覆盖 3 个动词：list / posts / articles。

X 搜索 / 订阅 / 取消订阅仅在 Web 控制台

X 账号搜索与订阅 / 取消订阅仅由 Web 控制台提供——CLI 与 Open API 都不暴露这些写类端点。脚本场景的标准做法：

在 Web 控制台「订阅管理 → X」完成搜索 + 订阅；
再用 mp2rss x list 列出已订阅账号、mp2rss x posts / x articles <xUserId> 拉取内容。

xUserId 是 X 账号的唯一数字 ID（不是 @handle，handle 可变更但 xUserId 稳定），需从 mp2rss x list 输出中取：

bash

mp2rss x list -o json | jq -r '.items[] | "\(.xUserId)\t@\(.xUsername)\t\(.xDisplayName)"'

`mp2rss x list`

列出当前 Feed 密钥下已订阅的全部 X 账号。

bash

mp2rss x list
mp2rss x list -q elon                    # 按 displayName / username 模糊搜索
mp2rss x list -p 2 --page-size 20
mp2rss x list -o json | jq '.items[].xUserId'

Flag	默认	含义
`-q, --query <kw>`	—	按 displayName / username 模糊匹配（服务端支持时生效）
`-p, --page <n>`	`1`	页码
`--page-size <n>`	`20`	每页记录数（最大 50）

HTTP 映射：GET /open-api/subscriptions?sourceType=x

表格输出示例：

X_USER_ID         用户名              显示名                    认证  最新内容             订阅时间
44196397          @elonmusk          Elon Musk                ✓     2026-05-13 09:14    2026-04-20 17:31

JSON 输出示例：

json

{
  "items": [
    {
      "sourceType": "x",
      "xUserId": "44196397",
      "xUsername": "elonmusk",
      "xDisplayName": "Elon Musk",
      "xVerified": true,
      "createdAt": 1776640000000,
      "xLastItemAt": 1776854096000
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

`mp2rss x posts`

按 postedAt DESC 拉取已订阅 X 账号的推文流。仅允许查询已订阅的 xUserId，未订阅返回 404 X account is not subscribed（退出码 4）。

bash

mp2rss x posts 44196397
mp2rss x posts 44196397 -p 2 --page-size 20
mp2rss x posts 44196397 -o json | jq '.items[].content'

Flag	默认	含义
`-p, --page <n>`	`1`	页码
`--page-size <n>`	`20`	每页记录数（最大 50）

HTTP 映射：GET /open-api/x/{xUserId}/posts

JSON 输出示例：

json

{
  "items": [
    {
      "postId": "1234567890",
      "content": "hello world",
      "media": [{ "url": "https://x.com/img.jpg", "type": "photo" }],
      "retweetedPost": null,
      "quotedPost": null,
      "threadPosts": [{ "content": "reply 1" }],
      "postedAt": 1746864000000
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20
}

结构化 vs 渲染

本端点返回结构化原始数据（含 media / quotedPost / threadPosts），供脚本 / 自定义渲染消费；要订阅供阅读器订阅请走 Feed 公开层 /feed/:token/rss/x-posts/...。

`mp2rss x articles`

按 publishedAt DESC 拉取已订阅 X 账号的长文（Articles）流。同样仅允许查询已订阅。

bash

mp2rss x articles 44196397
mp2rss x articles 44196397 -o json | jq '.items[].url'

Flag	默认	含义
`-p, --page <n>`	`1`	页码
`--page-size <n>`	`20`	每页记录数（最大 50）

HTTP 映射：GET /open-api/x/{xUserId}/articles

JSON 输出示例：

json

{
  "items": [
    {
      "url": "https://x.com/elonmusk/article/...",
      "title": "My take on...",
      "description": "summary",
      "contentMarkdown": "# Heading\n\nfull body markdown source",
      "coverUrl": "https://...",
      "publishedAt": 1747353600000
    }
  ],
  "total": 8,
  "page": 1,
  "pageSize": 20
}

contentMarkdown 为长文的 markdown 原文，可能为 null。

`mp2rss update`

自更新到 GitHub Releases 的最新版本。

bash

mp2rss update                # 检查并执行更新
mp2rss update --check        # 只检查不更新
mp2rss update --force        # 即使版本相同也强制重装

行为：

查询 https://api.github.com/.../releases/latest，按语义版本与本地比对（预发布版本视为更老）。
下载对应平台归档 + checksums.txt，校验 SHA-256。
暂存为 <selfpath>.new 后 os.Rename 原子替换；Windows 下若旧二进制被占用，会先改名 .old 再换入。
macOS 自动 xattr -d com.apple.quarantine 去掉 Gatekeeper 隔离属性。

通过 npm / 包管理器装的怎么升级？

仍可用 mp2rss update，但推荐改用对应包管理器（如 pnpm up -g @mp2rss/cli），避免下次包管理器升级时哈希校验冲突。详见 FAQ。

配置与环境变量

~/.mp2rss/config.json 字段（落盘 schema 保持 snake_case）：

json

{
  "feed_key": "9f3a2c...（64 位 hex）",
  "api_url": "https://mp2rss.bugcode.dev",
  "last_login_at": 1747194198,
  "last_verify_at": 1747194198
}

last_login_at / last_verify_at 为秒级 Unix 时间戳，分别记录最近一次成功登录与最近一次密钥校验成功的时刻。
文件权限自动设为 0600、目录权限 0700。

环境变量：

变量	作用	优先级
`MP2RSS_FEED_KEY`	覆盖 Feed 密钥	高于配置文件、低于 `--api-key`
`MP2RSS_API_URL`	覆盖 API 地址	高于配置文件、低于 `--api-url`

命令参考 ​

全局 flag ​

退出码 ​

mp2rss auth ​

mp2rss auth login ​

mp2rss auth logout ​

mp2rss auth status ​

mp2rss mp ​

mp2rss mp list ​

mp2rss mp search ​

mp2rss mp subscribe ​

mp2rss mp remove ​

mp2rss mp articles ​

mp2rss x ​

mp2rss x list ​

mp2rss x posts ​

mp2rss x articles ​

mp2rss update ​

配置与环境变量 ​

下一步 ​

命令参考

全局 flag

退出码

`mp2rss auth`

`mp2rss auth login`

`mp2rss auth logout`

`mp2rss auth status`

`mp2rss mp`

`mp2rss mp list`

`mp2rss mp search`

`mp2rss mp subscribe`

`mp2rss mp remove`

`mp2rss mp articles`

`mp2rss x`

`mp2rss x list`

`mp2rss x posts`

`mp2rss x articles`

`mp2rss update`

配置与环境变量

下一步