home / skills / openclaw / skills / sabnzbd

sabnzbd skill

safe

This skill helps you manage Usenet downloads via SABnzbd by checking queue, adding NZBs, and controlling the download lifecycle.

npx playbooks add skill openclaw/skills --skill sabnzbd

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.7 KB

---
name: sabnzbd
version: 1.0.0
description: Manage Usenet downloads with SABnzbd. Use when the user asks to "check SABnzbd", "list NZB queue", "add NZB", "pause downloads", "resume downloads", "SABnzbd status", "Usenet queue", "NZB history", or mentions SABnzbd/sab download management.
---

# SABnzbd API

Manage Usenet downloads via SABnzbd's REST API.

## Setup

Config: `~/.clawdbot/credentials/sabnzbd/config.json`

```json
{
  "url": "http://localhost:8080",
  "apiKey": "your-api-key-from-config-general"
}
```

Get your API key from SABnzbd Config → General → Security.

## Quick Reference

### Queue Status

```bash
# Full queue
./scripts/sab-api.sh queue

# With filters
./scripts/sab-api.sh queue --limit 10 --category tv

# Specific job
./scripts/sab-api.sh queue --nzo-id SABnzbd_nzo_xxxxx
```

### Add NZB

```bash
# By URL (indexer link)
./scripts/sab-api.sh add "https://indexer.com/get.php?guid=..."

# With options
./scripts/sab-api.sh add "URL" --name "My Download" --category movies --priority high

# By local file
./scripts/sab-api.sh add-file /path/to/file.nzb --category tv
```

Priority: `force`, `high`, `normal`, `low`, `paused`, `duplicate`

### Control Queue

```bash
./scripts/sab-api.sh pause              # Pause all
./scripts/sab-api.sh resume             # Resume all
./scripts/sab-api.sh pause-job <nzo_id>
./scripts/sab-api.sh resume-job <nzo_id>
./scripts/sab-api.sh delete <nzo_id>    # Keep files
./scripts/sab-api.sh delete <nzo_id> --files  # Delete files too
./scripts/sab-api.sh purge              # Clear queue
```

### Speed Control

```bash
./scripts/sab-api.sh speedlimit 50      # 50% of max
./scripts/sab-api.sh speedlimit 5M      # 5 MB/s
./scripts/sab-api.sh speedlimit 0       # Unlimited
```

### History

```bash
./scripts/sab-api.sh history
./scripts/sab-api.sh history --limit 20 --failed
./scripts/sab-api.sh retry <nzo_id>     # Retry failed
./scripts/sab-api.sh retry-all          # Retry all failed
./scripts/sab-api.sh delete-history <nzo_id>
```

### Categories & Scripts

```bash
./scripts/sab-api.sh categories
./scripts/sab-api.sh scripts
./scripts/sab-api.sh change-category <nzo_id> movies
./scripts/sab-api.sh change-script <nzo_id> notify.py
```

### Status & Info

```bash
./scripts/sab-api.sh status             # Full status
./scripts/sab-api.sh version
./scripts/sab-api.sh warnings
./scripts/sab-api.sh server-stats       # Download stats
```

## Response Format

Queue slot includes:
- `nzo_id`, `filename`, `status`
- `mb`, `mbleft`, `percentage`
- `timeleft`, `priority`, `cat`
- `script`, `labels`

Status values: `Downloading`, `Queued`, `Paused`, `Propagating`, `Fetching`

History status: `Completed`, `Failed`, `Queued`, `Verifying`, `Repairing`, `Extracting`

Overview

This skill manages Usenet downloads using SABnzbd's REST API. It lets you inspect the queue and history, add NZB files or URLs, control individual jobs or the entire queue, and view server status and speed limits. Use it to automate and monitor SABnzbd from chat. Credentials require the SABnzbd URL and API key in the configured credentials file.

How this skill works

The skill calls SABnzbd API endpoints to fetch queue, history, status, categories, and scripts, and to perform actions like add, pause, resume, delete, retry, and change metadata. It parses standard response fields (nzo_id, filename, status, mb, mbleft, percentage, timeleft, priority, cat, script, labels) and returns concise summaries or executes requested control commands. For uploads it can accept NZB URLs or local NZB files and supports priority and category options.

When to use it

When you want a quick summary of active Usenet downloads or overall SABnzbd status.
To add an NZB by URL or by uploading a local NZB file into the queue.
To pause, resume, delete, or change priority/category for one or all jobs.
To inspect download history, retry failed items, or clear history entries.
To adjust speed limits or retrieve server download statistics.

Best practices

Store the SABnzbd base URL and API key securely in the configured credentials file.
Use nzo_id when targeting specific jobs to avoid affecting the wrong item.
Apply categories and scripts when adding NZBs to ensure automated post-processing.
Prefer limited queries (limit, category) when listing large queues to keep responses concise.
Confirm delete-with-files actions intentionally; deletion can remove completed files.

Example use cases

User asks: 'check SABnzbd' — returns full status including queue count, download speed, and active jobs.
User asks: 'list NZB queue' with a category filter — returns queued and downloading slots for that category.
User requests: 'add NZB' with a URL and category — adds the URL with specified priority and category.
User commands: 'pause downloads' or 'resume downloads' — pauses or resumes the entire queue.
User asks: 'show NZB history' or 'retry failed' — lists recent history or retries a failed nzo_id.

FAQ

How do I target a single download?

Use the job's nzo_id returned in queue or history responses and pass it to pause-job, resume-job, delete, retry, or change-category commands.

Can I add NZBs by URL and set priority or category?

Yes. Provide the NZB URL and optional flags such as --name, --category, and --priority (force/high/normal/low/paused/duplicate) when adding.