GitHub

Manual

Command-Line Tool

motrix is the command-line client for Motrix. It is a client, not a download engine — it downloads nothing itself. Every command is a request to an already-running Motrix, and the actual transfer is performed by that instance.

The CLI speaks MDXP (the Motrix Download eXchange Protocol — JSON-RPC 2.0) over a unary POST /mdxp transport. The same binary talks to either target:

  • the desktop app on the same machine, auto-discovered with no configuration;
  • a remote or headless Motrix server, paired once and then reused.

Requirements

WhatRequirement
RuntimeNode.js 22 or newer
TargetA reachable, running Motrix instance (desktop app or server)
Package@motrix/cli on npm, installed globally

Install

Open Settings → Integration, find the Command-line tools section, and use the Motrix command-line tool card:

  1. Pick a package manager from the dropdown — npm, pnpm, Yarn Classic, Bun, or Volta.
  2. Click Install. Motrix runs the global install for you.
  3. When the badge turns Installed, open a new terminal and run motrix --help.

The card does more than run the installer. It checks your Node.js version first, verifies afterwards that motrix is actually resolvable on PATH, and reports the installed version, the executable path, and which package manager installed it. If something is off — Node.js too old, no supported package manager, a PATH entry shadowing the new binary — the badge switches to Needs attention with the specific reason and a Check again button.

Note

If the one-click install is unavailable — a sandboxed package, or the web/server build — the card says so and offers the command for you to copy and run yourself on the host where Motrix runs.

Manually

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

The published package is self-contained: the build inlines @motrix/mdxp, so a global install pulls in no @motrix/* runtime dependencies — only commander.

Warning

If the package manager cannot write to its global install directory, use a Node.js version manager or a user-writable prefix. Do not fix it with sudo — that leaves root-owned files in your global node_modules.

Quick start

motrix list                                            # current tasks
motrix add https://example.com/f.zip --save-dir ~/Downloads
motrix stats                                           # aggregate speeds and counts
motrix watch --stats                                   # stream live progress until Ctrl-C
motrix open                                            # launch the desktop app and wait for it

Command reference

CommandPurpose
motrix list [--status <s>] [--limit <n>] [--offset <n>]List download tasks
motrix statsAggregate speeds and task counts
motrix open [--timeout <ms>]Launch the local desktop app and wait until its bridge is ready
motrix add <url...> --save-dir <dir> [--filename <name>] [--header "K: V"] [--connections <n>] [--proxy <url>]Add HTTP(S) / FTP download(s)
motrix add --magnet <uri> --save-dir <dir> [--select 0,2]Add a magnet link
motrix add --torrent <file.torrent> --save-dir <dir>Add a .torrent file
motrix pause <taskId>Pause a task
motrix resume <taskId>Resume a task
motrix remove <taskId> [--delete-files]Remove a task
motrix watch [--task <id>] [--stats]Stream progress as NDJSON until interrupted
motrix pair [--name <label>]Pair with a Motrix bridge via device code
motrix describePrint the MDXP tool catalog
motrix skill path | install [dir]Locate or install the bundled agent skill
motrix self-update [target] [--dry-run]Update the CLI itself, using the package manager that installed it

motrix --version prints the CLI version.

Connecting to Motrix

Local desktop — zero configuration

By default the CLI discovers the running desktop app by reading <userData>/bridge/endpoint.json, which carries the bridge port and a machine-owner token:

PlatformPath
macOS~/Library/Application Support/Motrix/bridge/endpoint.json
Windows%APPDATA%\Motrix\bridge\endpoint.json
Linux$XDG_CONFIG_HOME/Motrix/bridge/endpoint.json (default ~/.config/Motrix/...)

Nothing to set up, and no pairing — a process that can read that file already has local machine access. If Motrix isn’t running, commands fail fast with exit code 3; run motrix open to start the desktop app first.

Remote or headless server — pair once

For a Motrix running elsewhere, run motrix pair once. It performs a device-code exchange over the REST /mdxp/pair/* routes and prints a verification code, which you then approve on the Motrix side:

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

On the Motrix side, the request surfaces in two places:

  • a toast reading <name> wants to pair with Motrix with the Verification code: shown underneath, plus Allow and Don’t allow buttons;
  • Settings → Integration → Pending approvals, which lists each waiting request with its client name, version, verification code, and remaining time, with Approve and Deny buttons.

Check that the code on screen matches the one your terminal printed, then approve. The issued token is stored in ~/.config/motrix/credentials.json (mode 0600, honoring XDG_CONFIG_HOME), keyed by endpoint, and reused automatically by later commands.

Approved clients appear under Paired remote tools in the same section. Click Revoke to invalidate a token — the CLI on that machine will then fail with exit code 4 until it pairs again.

Warning

A paired token grants full control over that Motrix, including adding downloads and deleting files with motrix remove --delete-files. Only approve a code you just generated yourself, and revoke tokens you no longer use.

Global flags

Every command accepts these:

FlagEffect
--endpoint <url>Target a specific bridge, e.g. http://nas.local:16801
--token <token>Supply a bearer token explicitly
--jsonEmit machine-readable JSON

MOTRIX_BRIDGE_TOKEN is the environment-variable equivalent of --token, which is usually the better choice in CI and scripts than putting a token in the command line.

Output and exit codes

The CLI adapts its output to the caller:

  • Interactive TTY → a human-readable table or summary.
  • --json, or piped / non-TTY stdout → a single JSON value, ready to parse. The JSON mode is implied when you pipe, so motrix list | jq works without the flag.

Scripts should branch on the exit code, not on parsed text:

CodeMeaning
0Success
2Usage error — bad flags or arguments
3Network — the bridge is down or unreachable
4Auth — token missing or rejected; re-run motrix pair
5Server — the bridge returned a JSON-RPC error
6Not installed — the desktop app could not be launched (motrix open)
7Self-update failed — unsupported install source, installer error, or verification mismatch

Version drift. If the target Motrix doesn’t recognize a method the CLI sends (JSON-RPC -32601), or exposes no /mdxp bridge at all (HTTP 404), the command exits 5 with a clear message asking you to update Motrix or the CLI — never a raw protocol error. In --json mode the original JSON-RPC code is preserved under data, so callers can still branch programmatically.

For AI agents

The CLI is designed to be driven safely by autonomous agents.

  • motrix describe --json emits the authoritative MDXP tool catalog: every agent-callable method with its JSON Schema (draft 2020-12) inputSchema and outputSchema. It is static — no bridge call — and always reflects the protocol version the CLI was built against, so it cannot drift from what the commands actually send. Use it to learn exact parameter shapes instead of guessing.
  • motrix skill install [dir] installs the bundled SKILL.md agent skill, by default into ~/.claude/skills under a motrix/ namespace. motrix skill path prints its location.
  • motrix watch streams progress as NDJSON — one JSON object per line — so an agent can follow a download without polling. --task <id> narrows it to one task; --stats restricts it to aggregate stats events.

Next steps