aria2-json-rpc - OpenClaw Directory

Source Code

What This Skill Does

This skill enables you to control aria2 download manager through natural language commands:

Download files (HTTP/HTTPS/FTP/Magnet/Torrent/Metalink)
Monitor download progress and status
Control downloads (pause, resume, remove)
Manage batch operations (pause all, resume all)
View statistics and configure options

How to Use (For AI Agents)

⚠️ CRITICAL: DO NOT manually construct JSON-RPC requests.

✅ ALWAYS use the Python scripts in the scripts/ directory.

⚠️ IMPORTANT: Use python3 command, NOT python (especially on macOS where python symlink doesn't exist)

Workflow (MUST FOLLOW)

Step 1: Check Configuration Status

Before executing any aria2 commands, ALWAYS check if configuration is ready:

python3 scripts/config_loader.py test

If successful: Proceed to execute user's command
If failed: Guide user to initialize configuration (see Step 2)

Step 2: Initialize Configuration (if needed)

If connection test fails, guide user to set up configuration:

# Recommended: User config (survives skill updates)
python3 scripts/config_loader.py init --user

# Alternative: Local config (project-specific)
python3 scripts/config_loader.py init --local

Then instruct user to edit the generated config file with their aria2 server details.

Step 3: Execute User Commands

Once configuration is ready, execute the requested aria2 operations.

Example Workflow

User: "download http://example.com/file.zip"

You execute:

# 1. Check configuration
python3 scripts/config_loader.py test

If test passes:

# 2. Execute download command
python3 scripts/rpc_client.py aria2.addUri '["http://example.com/file.zip"]'

You respond: "✓ Download started! GID: 2089b05ecca3d829"

If test fails:

Configuration not ready. Please initialize:
1. Run: python3 scripts/config_loader.py init --user
2. Edit ~/.config/aria2-skill/config.json with your aria2 server details
3. Run: python3 scripts/config_loader.py test (to verify)

Documentation Structure

For detailed execution instructions, see:

references/execution-guide.md - Complete guide for AI agents with:
- Command mapping table (user intent → script call)
- Parameter formatting rules
- Step-by-step examples
- Common mistakes to avoid
- Response formatting guidelines

For aria2 method reference, see:

references/aria2-methods.md - Detailed aria2 RPC method documentation

Common Commands Quick Reference

User Intent	Command Example
Download a file	`python3 scripts/rpc_client.py aria2.addUri '["http://example.com/file.zip"]'`
Check status	`python3 scripts/rpc_client.py aria2.tellStatus <GID>`
List active downloads	`python3 scripts/rpc_client.py aria2.tellActive`
List stopped downloads	`python3 scripts/rpc_client.py aria2.tellStopped 0 100`
Pause download	`python3 scripts/rpc_client.py aria2.pause <GID>`
Resume download	`python3 scripts/rpc_client.py aria2.unpause <GID>`
Show statistics	`python3 scripts/rpc_client.py aria2.getGlobalStat`
Show version	`python3 scripts/rpc_client.py aria2.getVersion`
Purge results	`python3 scripts/rpc_client.py aria2.purgeDownloadResult`

For detailed usage and more commands, see execution-guide.md.

Available Scripts

scripts/rpc_client.py - Main interface for RPC calls
scripts/examples/list-downloads.py - Formatted download list
scripts/examples/pause-all.py - Pause all downloads
scripts/examples/add-torrent.py - Add torrent downloads
scripts/examples/monitor-downloads.py - Real-time monitoring
scripts/examples/set-options.py - Modify options

Configuration

Scripts automatically load configuration from multiple sources with the following priority (highest to lowest):

Configuration Priority

Environment Variables (highest priority - temporary override)
- ARIA2_RPC_HOST, ARIA2_RPC_PORT, ARIA2_RPC_PATH, etc.
- Best for: CI/CD pipelines, temporary overrides, testing
- Note: For reference only. Agents should use config files instead.
Skill Directory Config (project-specific configuration)
- Location: skills/aria2-json-rpc/config.json
- Best for: Project-specific settings, local testing, development
- ⚠️ Warning: Lost when running npx skills add to update the skill
User Config Directory (global fallback, update-safe) 🆕
- Location: ~/.config/aria2-skill/config.json
- Best for: Personal default settings across all projects
- ✅ Safe: Survives skill updates via npx skills add
Defaults (localhost:6800)
- Zero-configuration fallback for local development

Configuration Options

host: Hostname or IP address (default: localhost)
port: Port number (default: 6800)
path: URL path (default: null). Set to /jsonrpc for standard aria2, or custom path for reverse proxy
secret: RPC secret token (default: null)
secure: Use HTTPS instead of HTTP (default: false)
timeout: Request timeout in milliseconds (default: 30000)

Quick Setup (For AI Agents)

IMPORTANT: Always use Python scripts to manage configuration. Do NOT use shell commands directly.

Step 1: Check current configuration status

python3 scripts/config_loader.py show

Step 2: Initialize configuration if needed

User config (recommended - survives updates):

python3 scripts/config_loader.py init --user

Local config (project-specific):

python3 scripts/config_loader.py init --local

Step 3: Guide user to edit the config file

After initialization, the tool will display the config file path. Instruct user to edit it with their aria2 server details (host, port, secret, etc.).

Step 4: Verify configuration

python3 scripts/config_loader.py test

Example config file content:

{
  "host": "localhost",
  "port": 6800,
  "secret": "your-secret-token",
  "secure": false,
  "timeout": 30000
}

Configuration Management (For AI Agents)

Available Python scripts for configuration management:

# Check current configuration and source
python3 scripts/config_loader.py show

# Initialize user config (recommended - update-safe)
python3 scripts/config_loader.py init --user

# Initialize local config (project-specific)
python3 scripts/config_loader.py init --local

# Test connection to aria2 server
python3 scripts/config_loader.py test

Agent Workflow for Configuration Setup:

Check if config exists: Run python3 scripts/config_loader.py show
If config missing or invalid: Guide user to run python3 scripts/config_loader.py init --user
User edits config: Tell user the file path and required fields (host, port, secret)
Verify setup: Run python3 scripts/config_loader.py test
Proceed with operations: Once test passes, execute user's aria2 commands

Advanced Configuration

Reverse Proxy Setup:

For reverse proxy setups like https://example.com:443/jsonrpc, the config file should contain:

{
  "host": "example.com",
  "port": 443,
  "path": "/jsonrpc",
  "secret": "your-secret-token",
  "secure": true
}

Environment Variables (for reference only):

Configuration can also be overridden via environment variables:

ARIA2_RPC_HOST: Hostname
ARIA2_RPC_PORT: Port number
ARIA2_RPC_PATH: URL path
ARIA2_RPC_SECRET: Secret token
ARIA2_RPC_SECURE: "true" or "false"

Note: Use Python scripts for configuration management. Environment variables are documented here for reference only.

Key Principles (For AI Agents)

Never construct JSON-RPC requests manually
Always call Python scripts via Bash tool using python3 (not python)
Always check configuration before executing commands:
- Run python3 scripts/config_loader.py test first
- If test fails, guide user through initialization
Never run raw shell commands (mkdir, cat, export, etc.) directly
- Use Python scripts: config_loader.py init, config_loader.py show, etc.
Parse script output and format for users
Refer to execution-guide.md when unsure

Supported Operations

Download Management

Add downloads (HTTP/FTP/Magnet/Torrent/Metalink)
Pause/resume (individual or all)
Remove downloads
Add with custom options

Monitoring

Check download status
List active/waiting/stopped downloads
Get global statistics
Real-time monitoring

Configuration

Get/change download options
Get/change global options
Query aria2 version
List available methods

Maintenance

Purge download results
Remove specific results

Need Help?

Execution details: references/execution-guide.md
Method reference: references/aria2-methods.md
Troubleshooting: references/troubleshooting.md
aria2 official docs: https://aria2.github.io/