命令行工具

motrix 是 Motrix 的命令行客户端。它是客户端，不是下载引擎——它自己不下载任何东西。每条命令都是发给一个正在运行的 Motrix 的请求，真正的传输由那个实例完成。

CLI 使用 MDXP（Motrix Download eXchange Protocol，基于 JSON-RPC 2.0）通过 unary POST /mdxp 传输通信。同一个可执行文件可以对接两种目标：

• 同一台机器上的桌面端 app，自动发现，零配置；
• 远程或 headless 的 Motrix server，配对一次后长期复用。

环境要求#

项目	要求
运行时	Node.js 22 或更新
目标	一个可访问的、正在运行的 Motrix 实例（桌面端 app 或 server）
安装包	npm 上的 @motrix/cli，全局安装

安装#

从桌面端安装（推荐）#

打开 设置 → 「集成」，找到 「命令行工具」 一节，使用 「Motrix 命令行工具」 卡片：

1. 在下拉框里选择包管理器——npm、pnpm、Yarn Classic、Bun 或 Volta。
2. 点击 「安装」，Motrix 会替你执行全局安装。
3. 状态标记变成 「已安装」 后，打开一个新终端，运行 motrix --help。

这张卡片做的事不止「跑一遍安装命令」。它会先检查 Node.js 版本，装完再验证 motrix 是否真的能在 PATH 中解析到，并显示已安装的版本、可执行文件路径，以及是哪个包管理器装的。如果有问题——Node.js 版本太旧、找不到受支持的包管理器、PATH 里有旧的同名可执行文件挡在前面——状态标记会变成 「需要处理」，给出具体原因和一个 「重新检查」 按钮。

手动安装#

npm i -g @motrix/cli
motrix --help

发布的包是自包含的：构建时已把 @motrix/mdxp inline 进产物，因此全局安装不会引入任何 @motrix/* 运行时依赖——只有一个 commander。

快速上手#

motrix list                                            # 当前任务
motrix add https://example.com/f.zip --save-dir ~/Downloads
motrix stats                                           # 聚合速度与任务计数
motrix watch --stats                                   # 持续输出实时进度,直到 Ctrl-C
motrix open                                            # 启动桌面端并等它就绪

命令一览#

命令	用途
motrix list [--status <s>] [--limit <n>] [--offset <n>]	列出下载任务
motrix stats	聚合速度与任务计数
motrix open [--timeout <ms>]	启动本地桌面端 app，并等待其 bridge 就绪
motrix add <url...> --save-dir <dir> [--filename <name>] [--header "K: V"] [--connections <n>] [--proxy <url>]	添加 HTTP(S) / FTP 下载
motrix add --magnet <uri> --save-dir <dir> [--select 0,2]	添加 magnet 链接
motrix add --torrent <file.torrent> --save-dir <dir>	添加 .torrent 文件
motrix pause <taskId>	暂停任务
motrix resume <taskId>	恢复任务
motrix remove <taskId> [--delete-files]	移除任务
motrix watch [--task <id>] [--stats]	以 NDJSON 流式输出进度，直到中断
motrix pair [--name <label>]	通过 device code 与 Motrix bridge 配对
motrix describe	打印 MDXP 工具目录
motrix skill path | install [dir]	定位或安装内置的 agent skill
motrix self-update [target] [--dry-run]	用当初安装它的包管理器更新 CLI 自身

motrix --version 打印 CLI 版本。

连接到 Motrix#

本地桌面端——零配置#

默认情况下，CLI 会读取 <userData>/bridge/endpoint.json 来发现正在运行的桌面端，该文件携带 bridge 端口和一个 machine-owner token：

平台	路径
macOS	~/Library/Application Support/Motrix/bridge/endpoint.json
Windows	%APPDATA%\Motrix\bridge\endpoint.json
Linux	$XDG_CONFIG_HOME/Motrix/bridge/endpoint.json(默认 ~/.config/Motrix/...)

不需要任何设置，也不需要配对——能读到这个文件的进程，本来就已经拥有本机权限了。如果 Motrix 没在运行，命令会立刻以退出码 3 失败；先运行 motrix open 把桌面端拉起来。

远程或 headless server——配对一次#

要连接跑在别处的 Motrix，先运行一次 motrix pair。它会通过 REST /mdxp/pair/* 路由完成 device-code 交换，并打印一个验证码，你在 Motrix 一侧批准它：

motrix pair --endpoint http://nas.local:16801 --name "laptop"

在 Motrix 一侧，这个请求会出现在两个地方：

• 一条提示 「<name> 想与 Motrix 配对」 的通知，下方显示 「验证码：」，并带 「允许」 和 「拒绝」 两个按钮；
• 设置 → 「集成」→「待审批」，这里列出每个等待中的请求，包含客户端名称、版本、验证码和剩余时间，以及 「批准」 和 「拒绝」 按钮。

先核对屏幕上的验证码与终端打印的是否一致，再批准。签发的 token 会以 endpoint 为键，存入 ~/.config/motrix/credentials.json(权限 0600，遵循 XDG_CONFIG_HOME)，后续命令自动复用。

已批准的客户端会出现在同一节的 「已配对的远程工具」 下。点 「撤销」 可以让某个 token 失效——那台机器上的 CLI 之后会以退出码 4 失败，直到重新配对。

全局 flag#

所有命令都接受这几个：

Flag	作用
--endpoint <url>	指定 bridge 地址，例如 http://nas.local:16801
--token <token>	显式提供 bearer token
--json	输出机器可读的 JSON

环境变量 MOTRIX_BRIDGE_TOKEN 等价于 --token。在 CI 和脚本里通常更推荐用它，而不是把 token 写在命令行上。

输出与退出码#

CLI 会根据调用方自动调整输出：

• 交互式 TTY → 人类可读的表格或摘要。
• --json，或被管道 / 非 TTY 的 stdout → 单个 JSON 值，便于解析。管道时会自动进入 JSON 模式，所以 motrix list | jq 不加 flag 也能用。

脚本应该基于退出码分支，而不是去解析文本：

退出码	含义
0	成功
2	用法错误——flag 或参数有误
3	网络——bridge 未启动或不可达
4	认证——token 缺失或被拒，重新运行 motrix pair
5	服务端——bridge 返回了 JSON-RPC error
6	未安装——无法启动桌面端 app(motrix open)
7	self-update 失败——安装源不支持、安装器报错，或安装后验证不匹配

版本漂移。 如果目标 Motrix 不认识 CLI 发送的某个方法(JSON-RPC -32601)，或者根本没有暴露 /mdxp bridge（HTTP 404），命令会以退出码 5 失败，并给出清晰的「请升级 Motrix 或 CLI」提示，而不是抛出原始协议错误。在 --json 模式下，原始 JSON-RPC code 会保留在 data 中，调用方仍可编程分支。

给 AI agent 使用#

这个 CLI 从设计上就适合被自主 agent 安全驱动。

• motrix describe --json 输出权威的 MDXP 工具目录：每个 agent 可调用的方法，及其 JSON Schema（draft 2020-12）的 inputSchema 与 outputSchema。它是静态的——不发起任何 bridge 调用——且始终反映 CLI 构建时所针对的协议版本，因此不会与命令实际发送的内容产生漂移。用它拿到精确的参数结构，而不是靠猜。
• motrix skill install [dir] 安装内置的 SKILL.md agent skill，默认装到 ~/.claude/skills 的 motrix/ 命名空间下。motrix skill path 打印它的路径。
• motrix watch 以 NDJSON 流式输出进度——每行一个 JSON 对象——agent 可以据此跟踪下载而不必轮询。--task <id> 只看某一个任务，--stats 只保留聚合统计事件。

接下来#

• 服务器部署——跑一个 headless Motrix 供 CLI 驱动。
• 浏览器扩展——MDXP bridge 的另一半，用于从网页发送下载。