motrix-cli

Control Motrix Next and legacy Motrix downloads from the terminal through their local aria2 JSON-RPC backend.

Translations: 简体中文 | 日本語 | 한국어 | Español | Português | Français | Deutsch | Русский

motrix-cli is built for both humans and AI agents: it has a small command set, stable JSON output, a one-line installer, and a reusable Codex skill.

Keywords: Motrix CLI, aria2 RPC, aria2 JSON-RPC, download automation, AI agent download tool, Codex skill.

AI Agent Workflow

motrix-cli is designed so Codex, Hermes, and other AI agents can control Motrix downloads through a predictable command-line interface.

Why Use It

Motrix Next and legacy Motrix run aria2 under the hood, but controlling downloads reliably from scripts or AI agents is awkward without a small wrapper. motrix-cli gives agents and people a predictable interface for adding downloads, checking progress, and waiting for completion without touching the GUI.

Use it when you want to:

• add download tasks from a terminal or agent
• list active, waiting, stopped, and completed downloads
• inspect a task by GID
• pause, resume, remove, or clean up tasks
• wait until a download finishes
• return machine-readable JSON for automation
• diagnose target app RPC configuration problems

Install

Install directly from GitHub:

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

By default this installs to:

~/.local/bin/motrix-cli

Make sure ~/.local/bin is in your PATH.

To install to another directory:

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

Or clone the repo, then run:

./install.sh

You can also install manually:

mkdir -p ~/.local/bin
cp bin/motrix-cli ~/.local/bin/motrix-cli
chmod +x ~/.local/bin/motrix-cli

Quick Start For Humans

First, launch Motrix Next and check that RPC works:

motrix-cli doctor

Add a download:

motrix-cli add "https://example.com/file.zip"

Add a download and wait until it finishes:

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

List tasks:

motrix-cli list

Show one task:

motrix-cli stat <gid>

Wait for a task to finish:

motrix-cli wait <gid>

Quick Start For AI Agents

Agents should use JSON mode and treat ok: false plus a nonzero exit code as failure.

motrix-cli doctor --json
motrix-cli download --json "https://example.com/file.zip"
motrix-cli add --json "https://example.com/file.zip"
motrix-cli list --json
motrix-cli stat --json <gid>
motrix-cli wait --json <gid>

Recommended flow:

1. Run motrix-cli doctor --json.
2. If Motrix Next is not running, run motrix-cli open --json, wait briefly, then run doctor again.
3. Download with motrix-cli download --json "<url>" --timeout 3600.
4. Read the returned gid and final task.
5. If needed, inspect with motrix-cli stat --json "<gid>" or motrix-cli list --json.

JSON responses use ok: true for success. Errors return ok: false and a nonzero exit code. JSON output includes a target object so automation can see which app and RPC endpoint are being controlled.

Example agent prompt:

Use motrix-cli to add this URL to Motrix Next, wait for completion, and report the final local path.

Automation Contract

The JSON output is the stable automation interface. Successful commands include ok: true; failed commands include ok: false and exit nonzero. JSON responses also include a target object whenever the command resolved a target app, so agents can confirm which Motrix app and RPC endpoint they controlled.

The test suite protects this contract for core commands and error paths:

python -m unittest discover -s tests -v

Codex Skill

This repository includes a reusable Codex skill at:

skills/motrix-cli

If you already cloned this repository, install the skill locally with:

mkdir -p ~/.codex/skills
cp -R skills/motrix-cli ~/.codex/skills/motrix-cli

If you only have the GitHub URL, clone and install the skill with:

tmpdir="$(mktemp -d)"
git clone https://github.com/nufegia/motrix-cli.git "$tmpdir/motrix-cli"
mkdir -p ~/.codex/skills
cp -R "$tmpdir/motrix-cli/skills/motrix-cli" ~/.codex/skills/motrix-cli

After installation, ask an agent to use $motrix-cli when it needs to install or control Motrix Next or legacy Motrix downloads.

Example:

Use $motrix-cli to download this file with Motrix Next and wait until it finishes.

Requirements

• macOS
• Python 3.9 or newer
• Motrix Next or legacy Motrix installed
• The target app running when you use the CLI

Motrix Next and legacy Motrix normally start aria2 RPC on port 16800. This tool defaults to Motrix Next and reads its local config file by default:

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

Legacy Motrix is still supported with --app motrix or MOTRIX_APP=motrix:

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

Those files may contain your local RPC secret. Do not commit them to Git.

This tool controls the target app through the local aria2 RPC endpoint. It does not automate or remote-control the GUI.

Platform Limits

motrix-cli is currently designed for macOS first.

• The default Motrix Next and legacy Motrix config paths are macOS-specific.
• motrix-cli open uses the macOS open -a MotrixNext command by default. Use --app motrix to launch legacy Motrix.
• The app install directory usually does not matter on macOS, as long as the system can launch the target app and its RPC service is running.
• Windows and Linux may work only when you manually provide RPC settings with MOTRIX_RPC_URL, MOTRIX_RPC_HOST, MOTRIX_RPC_PORT, MOTRIX_RPC_SECRET, or MOTRIX_CONFIG.
• The target app must be installed and running for most commands, because this tool talks to its local aria2 RPC service.

Commands

motrix-cli add <url> [--dir DIR] [--out NAME] [--pause]
motrix-cli download <url> [--dir DIR] [--out NAME] [--timeout SECONDS] [--interval SECONDS]
motrix-cli list [--status all|active|waiting|stopped] [--limit N]
motrix-cli stat <gid>
motrix-cli wait <gid> [--timeout SECONDS] [--interval SECONDS]
motrix-cli pause <gid>
motrix-cli resume <gid>
motrix-cli remove <gid>
motrix-cli remove-result <gid>
motrix-cli pause-all
motrix-cli resume-all
motrix-cli purge-completed
motrix-cli version
motrix-cli rpc-version
motrix-cli doctor
motrix-cli open
motrix-cli rpc <method> '[params-json-array]'

motrix-cli version shows the CLI's own version. motrix-cli rpc-version queries the target app's aria2 RPC backend version and requires the target app to be running.

Global flags:

--app APP     Target app: motrix-next, motrix, or auto. Default: motrix-next
--json       Output machine-readable JSON
--no-color   Disable colored output

Global flags can appear before or after the command:

motrix-cli --json list
motrix-cli list --json
motrix-cli --app motrix list
motrix-cli list --app motrix-next

Configuration

The CLI reads the target app config automatically on macOS. The default target is motrix-next. Select another target with --app or MOTRIX_APP:

motrix-cli --app motrix-next doctor
motrix-cli --app motrix doctor
MOTRIX_APP=motrix motrix-cli list

You can override the RPC settings with environment variables:

MOTRIX_APP             Target app: motrix-next, motrix, or auto
MOTRIX_CONFIG          Path to target app system.json
MOTRIX_RPC_HOST        RPC host, default: localhost
MOTRIX_RPC_PORT        RPC port, default: value from target app config or 16800
MOTRIX_RPC_SECRET      RPC secret, default: value from target app config
MOTRIX_RPC_URL         Full RPC URL, default: http://HOST:PORT/jsonrpc
MOTRIX_CONNECT_TIMEOUT Connection timeout hint in seconds
MOTRIX_RPC_TIMEOUT     RPC timeout hint in seconds

Example:

MOTRIX_RPC_SECRET="your-secret" motrix-cli doctor

Troubleshooting

Run:

motrix-cli doctor

Common issues:

• The target app is not running.
• The target app RPC is disabled or using a different port.
• The RPC secret in the target app changed.
• motrix-cli is not in your PATH.

If the target app is closed, you can ask macOS to launch it:

motrix-cli open

Then run motrix-cli doctor again.

Security Notes

This tool reads your local RPC secret so it can authenticate to aria2. It does not send that secret anywhere except to your local target app/aria2 RPC endpoint.

Do not publish:

• your Motrix Next or Motrix system.json
• screenshots or logs containing your RPC secret
• local backup files containing hardcoded secrets

License

MIT