{"skill":{"slug":"aria2-json-rpc","displayName":"Aria2 Json Rpc","summary":"Interact with aria2 download manager via JSON-RPC 2.0. Manage downloads, query status, and control tasks through natural language commands. Use when working with aria2, download management, or torrent operations.","description":"---\nname: aria2-json-rpc\ndescription: Interact with aria2 download manager via JSON-RPC 2.0. Manage downloads, query status, and control tasks through natural language commands. Use when working with aria2, download management, or torrent operations.\nlicense: MIT\ncompatibility: Requires Python 3.6+. WebSocket support requires websockets package (pip install websockets) and Python version must match dependency requirements.\nmetadata:\n  author: ISON\n  version: \"1.1.0\"\n---\n\n## What This Skill Does\n\nThis skill enables you to control aria2 download manager through natural language commands:\n- Download files (HTTP/HTTPS/FTP/Magnet/Torrent/Metalink)\n- Monitor download progress and status\n- Control downloads (pause, resume, remove)\n- Manage batch operations (pause all, resume all)\n- View statistics and configure options\n\n## How to Use (For AI Agents)\n\n**⚠️ CRITICAL: DO NOT manually construct JSON-RPC requests.**\n\n**✅ ALWAYS use the Python scripts in the `scripts/` directory.**\n\n**⚠️ IMPORTANT: Use `python3` command, NOT `python`** (especially on macOS where `python` symlink doesn't exist)\n\n### Workflow (MUST FOLLOW)\n\n**Step 1: Check Configuration Status**\n\nBefore executing any aria2 commands, ALWAYS check if configuration is ready:\n\n```bash\npython3 scripts/config_loader.py test\n```\n\n- If **successful**: Proceed to execute user's command\n- If **failed**: Guide user to initialize configuration (see Step 2)\n\n**Step 2: Initialize Configuration (if needed)**\n\nIf connection test fails, guide user to set up configuration:\n\n```bash\n# Recommended: User config (survives skill updates)\npython3 scripts/config_loader.py init --user\n\n# Alternative: Local config (project-specific)\npython3 scripts/config_loader.py init --local\n```\n\nThen instruct user to edit the generated config file with their aria2 server details.\n\n**Step 3: Execute User Commands**\n\nOnce configuration is ready, execute the requested aria2 operations.\n\n### Example Workflow\n\n**User:** \"download http://example.com/file.zip\"\n\n**You execute:**\n```bash\n# 1. Check configuration\npython3 scripts/config_loader.py test\n```\n\nIf test passes:\n```bash\n# 2. Execute download command\npython3 scripts/rpc_client.py aria2.addUri '[\"http://example.com/file.zip\"]'\n```\n\n**You respond:** \"✓ Download started! GID: 2089b05ecca3d829\"\n\nIf test fails:\n```\nConfiguration not ready. Please initialize:\n1. Run: python3 scripts/config_loader.py init --user\n2. Edit ~/.config/aria2-skill/config.json with your aria2 server details\n3. Run: python3 scripts/config_loader.py test (to verify)\n```\n\n## Documentation Structure\n\n**For detailed execution instructions, see:**\n- **[references/execution-guide.md](references/execution-guide.md)** - Complete guide for AI agents with:\n  - Command mapping table (user intent → script call)\n  - Parameter formatting rules\n  - Step-by-step examples\n  - Common mistakes to avoid\n  - Response formatting guidelines\n\n**For aria2 method reference, see:**\n- **[references/aria2-methods.md](references/aria2-methods.md)** - Detailed aria2 RPC method documentation\n\n## Common Commands Quick Reference\n\n| User Intent | Command Example |\n|-------------|----------------|\n| Download a file | `python3 scripts/rpc_client.py aria2.addUri '[\"http://example.com/file.zip\"]'` |\n| Check status | `python3 scripts/rpc_client.py aria2.tellStatus <GID>` |\n| List active downloads | `python3 scripts/rpc_client.py aria2.tellActive` |\n| List stopped downloads | `python3 scripts/rpc_client.py aria2.tellStopped 0 100` |\n| Pause download | `python3 scripts/rpc_client.py aria2.pause <GID>` |\n| Resume download | `python3 scripts/rpc_client.py aria2.unpause <GID>` |\n| Show statistics | `python3 scripts/rpc_client.py aria2.getGlobalStat` |\n| Show version | `python3 scripts/rpc_client.py aria2.getVersion` |\n| Purge results | `python3 scripts/rpc_client.py aria2.purgeDownloadResult` |\n\nFor detailed usage and more commands, see [execution-guide.md](references/execution-guide.md).\n\n## Available Scripts\n\n- `scripts/rpc_client.py` - Main interface for RPC calls\n- `scripts/examples/list-downloads.py` - Formatted download list\n- `scripts/examples/pause-all.py` - Pause all downloads\n- `scripts/examples/add-torrent.py` - Add torrent downloads\n- `scripts/examples/monitor-downloads.py` - Real-time monitoring\n- `scripts/examples/set-options.py` - Modify options\n\n## Configuration\n\nScripts automatically load configuration from multiple sources with the following priority (highest to lowest):\n\n### Configuration Priority\n\n1. **Environment Variables** (highest priority - temporary override)\n   - `ARIA2_RPC_HOST`, `ARIA2_RPC_PORT`, `ARIA2_RPC_PATH`, etc.\n   - Best for: CI/CD pipelines, temporary overrides, testing\n   - **Note**: For reference only. Agents should use config files instead.\n\n2. **Skill Directory Config** (project-specific configuration)\n   - Location: `skills/aria2-json-rpc/config.json`\n   - Best for: Project-specific settings, local testing, development\n   - ⚠️ **Warning**: Lost when running `npx skills add` to update the skill\n\n3. **User Config Directory** (global fallback, update-safe) 🆕\n   - Location: `~/.config/aria2-skill/config.json`\n   - Best for: Personal default settings across all projects\n   - ✅ **Safe**: Survives skill updates via `npx skills add`\n\n4. **Defaults** (localhost:6800)\n   - Zero-configuration fallback for local development\n\n### Configuration Options\n\n- **host**: Hostname or IP address (default: `localhost`)\n- **port**: Port number (default: `6800`)\n- **path**: URL path (default: `null`). Set to `/jsonrpc` for standard aria2, or custom path for reverse proxy\n- **secret**: RPC secret token (default: `null`)\n- **secure**: Use HTTPS instead of HTTP (default: `false`)\n- **timeout**: Request timeout in milliseconds (default: `30000`)\n\n### Quick Setup (For AI Agents)\n\n**IMPORTANT**: Always use Python scripts to manage configuration. Do NOT use shell commands directly.\n\n**Step 1: Check current configuration status**\n```bash\npython3 scripts/config_loader.py show\n```\n\n**Step 2: Initialize configuration if needed**\n\nUser config (recommended - survives updates):\n```bash\npython3 scripts/config_loader.py init --user\n```\n\nLocal config (project-specific):\n```bash\npython3 scripts/config_loader.py init --local\n```\n\n**Step 3: Guide user to edit the config file**\n\nAfter initialization, the tool will display the config file path. Instruct user to edit it with their aria2 server details (host, port, secret, etc.).\n\n**Step 4: Verify configuration**\n```bash\npython3 scripts/config_loader.py test\n```\n\nExample config file content:\n```json\n{\n  \"host\": \"localhost\",\n  \"port\": 6800,\n  \"secret\": \"your-secret-token\",\n  \"secure\": false,\n  \"timeout\": 30000\n}\n```\n\n### Configuration Management (For AI Agents)\n\n**Available Python scripts for configuration management:**\n\n```bash\n# Check current configuration and source\npython3 scripts/config_loader.py show\n\n# Initialize user config (recommended - update-safe)\npython3 scripts/config_loader.py init --user\n\n# Initialize local config (project-specific)\npython3 scripts/config_loader.py init --local\n\n# Test connection to aria2 server\npython3 scripts/config_loader.py test\n```\n\n**Agent Workflow for Configuration Setup:**\n\n1. **Check if config exists**: Run `python3 scripts/config_loader.py show`\n2. **If config missing or invalid**: Guide user to run `python3 scripts/config_loader.py init --user`\n3. **User edits config**: Tell user the file path and required fields (host, port, secret)\n4. **Verify setup**: Run `python3 scripts/config_loader.py test`\n5. **Proceed with operations**: Once test passes, execute user's aria2 commands\n\n### Advanced Configuration\n\n**Reverse Proxy Setup:**\n\nFor reverse proxy setups like `https://example.com:443/jsonrpc`, the config file should contain:\n\n```json\n{\n  \"host\": \"example.com\",\n  \"port\": 443,\n  \"path\": \"/jsonrpc\",\n  \"secret\": \"your-secret-token\",\n  \"secure\": true\n}\n```\n\n**Environment Variables (for reference only):**\n\nConfiguration can also be overridden via environment variables:\n- `ARIA2_RPC_HOST`: Hostname\n- `ARIA2_RPC_PORT`: Port number\n- `ARIA2_RPC_PATH`: URL path\n- `ARIA2_RPC_SECRET`: Secret token\n- `ARIA2_RPC_SECURE`: \"true\" or \"false\"\n\nNote: Use Python scripts for configuration management. Environment variables are documented here for reference only.\n\n## Key Principles (For AI Agents)\n\n1. **Never** construct JSON-RPC requests manually\n2. **Always** call Python scripts via Bash tool using `python3` (not `python`)\n3. **Always** check configuration before executing commands:\n   - Run `python3 scripts/config_loader.py test` first\n   - If test fails, guide user through initialization\n4. **Never** run raw shell commands (mkdir, cat, export, etc.) directly\n   - Use Python scripts: `config_loader.py init`, `config_loader.py show`, etc.\n5. **Parse** script output and format for users\n6. **Refer to** execution-guide.md when unsure\n\n## Supported Operations\n\n### Download Management\n- Add downloads (HTTP/FTP/Magnet/Torrent/Metalink)\n- Pause/resume (individual or all)\n- Remove downloads\n- Add with custom options\n\n### Monitoring\n- Check download status\n- List active/waiting/stopped downloads\n- Get global statistics\n- Real-time monitoring\n\n### Configuration\n- Get/change download options\n- Get/change global options\n- Query aria2 version\n- List available methods\n\n### Maintenance\n- Purge download results\n- Remove specific results\n\n## Need Help?\n\n- **Execution details:** [references/execution-guide.md](references/execution-guide.md)\n- **Method reference:** [references/aria2-methods.md](references/aria2-methods.md)\n- **Troubleshooting:** [references/troubleshooting.md](references/troubleshooting.md)\n- **aria2 official docs:** https://aria2.github.io/\n","topics":["Json"],"tags":{"latest":"0.1.0"},"stats":{"comments":0,"downloads":2038,"installsAllTime":76,"installsCurrent":2,"stars":1,"versions":2},"createdAt":1770270471147,"updatedAt":1778486025837},"latestVersion":{"version":"0.1.0","createdAt":1770273051710,"changelog":"No changes detected in code or documentation for version 0.1.0.\n\n- Initial version; no updates since previous release.\n- Functionality and documentation remain the same.","license":null},"metadata":null,"owner":{"handle":"azzgo","userId":"s178tx7j9wp5emdjc3y71wbfah884c35","displayName":"azzgo","image":"https://avatars.githubusercontent.com/u/5636512?v=4"},"moderation":null}