Motrix cli

Motrix CLI

Overview

Use motrix-cli to control Motrix Next or legacy Motrix downloads from an agent-friendly terminal workflow. Prefer --json for automation and treat the target as a local app: it must be installed and running, and its aria2 RPC endpoint must be reachable.

By default, motrix-cli targets Motrix Next. Use --app motrix or MOTRIX_APP=motrix for legacy Motrix. JSON responses include target, which identifies the app, config path, RPC URL, and whether the RPC secret is set.

Install Or Locate

Check whether the command is already available:

command -v motrix-cli
motrix-cli doctor --json

If it is missing, install it from GitHub:

curl -fsSL https://raw.githubusercontent.com/nufegia/motrix-cli/main/install.sh | bash

The default install path is ~/.local/bin/motrix-cli. If ~/.local/bin is not in PATH, either add it to PATH or run the full path:

~/.local/bin/motrix-cli doctor --json

To install somewhere else:

curl -fsSL https://raw.githubusercontent.com/nufegia/motrix-cli/main/install.sh | INSTALL_DIR=/usr/local/bin bash

Agent Workflow

1. Run motrix-cli doctor --json.
2. If Motrix Next is not running, run motrix-cli open --json, wait briefly, then run motrix-cli doctor --json again.
3. Prefer one-step downloads with motrix-cli download --json "<url>" --timeout <seconds>.
4. Read the returned gid and final task.
5. Inspect details with motrix-cli stat --json "<gid>" or motrix-cli list --json if needed.

Example:

motrix-cli doctor --json
motrix-cli download --json "https://example.com/file.zip" --timeout 3600

To target legacy Motrix explicitly:

motrix-cli --app motrix doctor --json
motrix-cli --app motrix download --json "https://example.com/file.zip"

Common Commands

Use these forms in automation:

motrix-cli list --json
motrix-cli download --json "https://example.com/file.zip" --timeout 3600
motrix-cli download --json "https://example.com/file.zip" --dir "$HOME/Downloads" --out "file.zip"
motrix-cli list --json --status active
motrix-cli stat --json "<gid>"
motrix-cli pause --json "<gid>"
motrix-cli resume --json "<gid>"
motrix-cli remove --json "<gid>"
motrix-cli remove-result --json "<gid>"
motrix-cli purge-completed --json
motrix-cli version --json
motrix-cli rpc-version --json

Use motrix-cli version to check the CLI's own version. Use motrix-cli rpc-version to query the target app's aria2 RPC backend version; it requires the target app to be running.

Use download when the user wants the file downloaded and completed before continuing. Use add when the user only wants to enqueue a task without waiting.

For a specific destination or output filename:

motrix-cli add --json "https://example.com/file.zip" --dir "$HOME/Downloads" --out "file.zip"

JSON Handling

Successful JSON responses include ok: true. Failed JSON responses include ok: false and the command exits nonzero. Always check both the exit code and the ok field when writing robust automation.

Important fields:

• target.app: motrix-next or motrix
• target.configPath: config file used for RPC settings
• target.rpcUrl: local aria2 JSON-RPC endpoint
• gid: aria2 task id returned by add
• task.status: usually active, waiting, paused, complete, error, or removed
• task.progress: percent complete
• task.path: local file path when available
• task.errorMessage: human-readable failure detail when available

Configuration

By default the CLI reads Motrix Next's macOS config from:

~/Library/Application Support/com.motrix.next/system.json

Legacy Motrix uses:

~/Library/Application Support/Motrix/system.json

Override RPC settings only when needed:

MOTRIX_RPC_HOST=localhost MOTRIX_RPC_PORT=16800 MOTRIX_RPC_SECRET="secret" motrix-cli doctor --json

Supported environment variables:

MOTRIX_APP
MOTRIX_CONFIG
MOTRIX_RPC_HOST
MOTRIX_RPC_PORT
MOTRIX_RPC_SECRET
MOTRIX_RPC_URL
MOTRIX_CONNECT_TIMEOUT
MOTRIX_RPC_TIMEOUT

Safety

Do not print, commit, or share the target app's RPC secret. Do not include system.json in logs or artifacts. Before removing active tasks, make sure the user intended to cancel that download and that target.app is the intended app; remove-result only clears completed/stopped records.