# Motrix Cli

> Control Motrix Next and legacy Motrix downloads through the motrix-cli command-line tool and their local aria2 JSON-RPC backend. Use when an agent needs to install motrix-cli, diagnose Motrix RPC connectivity, add download URLs, list or inspect tasks, pause/resume/remove tasks, wait for downloads to finish, or automate downloads with machine-readable JSON output on macOS.

- **Type:** Skill
- **Install:** `agentstack add skill-nufegia-motrix-cli-motrix-cli`
- **Verified:** Pending review
- **Seller:** [nufegia](https://agentstack.voostack.com/s/nufegia)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nufegia](https://github.com/nufegia)
- **Source:** https://github.com/nufegia/motrix-cli/tree/main/skills/motrix-cli

## Install

```sh
agentstack add skill-nufegia-motrix-cli-motrix-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
command -v motrix-cli
motrix-cli doctor --json
```

If it is missing, install it from GitHub:

```bash
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:

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

To install somewhere else:

```bash
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 "" --timeout `.
4. Read the returned `gid` and final `task`.
5. Inspect details with `motrix-cli stat --json ""` or `motrix-cli list --json` if needed.

Example:

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

To target legacy Motrix explicitly:

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

## Common Commands

Use these forms in automation:

```bash
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 ""
motrix-cli pause --json ""
motrix-cli resume --json ""
motrix-cli remove --json ""
motrix-cli remove-result --json ""
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:

```bash
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:

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

Legacy Motrix uses:

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

Override RPC settings only when needed:

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

Supported environment variables:

```text
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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nufegia](https://github.com/nufegia)
- **Source:** [nufegia/motrix-cli](https://github.com/nufegia/motrix-cli)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nufegia-motrix-cli-motrix-cli
- Seller: https://agentstack.voostack.com/s/nufegia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.