sabx

name	sabx
version	0.1.11
description	Control SABnzbd download manager via CLI. Use when users need to check download queue/history, add NZBs, manage priorities, control speed limits, pause/resume downloads, configure RSS feeds, run scheduled tasks, or automate Usenet workflows. Triggers include "sabnzbd", "sabx", "downloads", "nzb", "usenet", "download queue", "download status".
metadata	{"short-description":"SABnzbd CLI for download automation","compatibility":"claude-code, codex-cli"}

SABnzbd CLI (sabx)

Control SABnzbd from the terminal. Covers common SABnzbd API operations.

Prerequisites

# Install (Go 1.24+)
go install github.com/avivsinai/sabx/cmd/sabx@latest

# Authenticate (stores API key in OS keyring)
sabx login --base-url http://localhost:8080 --api-key <key>

Quick Command Reference

Task	Command
Queue status	sabx queue list
Active downloads	sabx queue list --active
Add NZB from URL	sabx queue add url <url>
Add NZB file	sabx queue add file <path>
Pause queue	sabx queue pause
Resume queue	sabx queue resume
Set priority	sabx queue item priority <nzo_id> 2
Delete item	sabx queue item delete <nzo_id>
History	sabx history list
Retry failed	sabx history retry <nzo_id>
Delete all history	sabx history delete --all
System status	sabx status
Full diagnostics	sabx status --full --performance
Speed status	sabx speed status
Set speed limit	sabx speed limit --rate 5M
Remove speed limit	sabx speed limit --none
Live dashboard	sabx top

Priority Values

Priority is -1 to 2: -1=low, 0=normal, 1=high, 2=force

Common Patterns

Check and manage downloads

sabx queue list --active          # What's downloading now
sabx status --full                # Overall system health
sabx speed status                 # Current speed and limits
sabx warnings list                # Any runtime issues

Add downloads

sabx queue add url https://example.com/file.nzb
sabx queue add file ./local.nzb --cat movies
sabx queue add local /path/on/server/file.nzb

Priority and queue management

sabx queue item priority <nzo_id> 2    # Force (2=force priority)
sabx queue item move <nzo_id> top      # Move to top
sabx queue item move <nzo_id> to 0     # Move to position 0
sabx queue sort name                   # Sort by name
sabx history delete --all              # Clear entire history
sabx history delete --failed           # Clear failed items only

Pause/resume workflows

sabx queue pause                  # Pause all downloads
sabx queue resume                 # Resume downloads
sabx postprocess pause            # Pause post-processing
sabx postprocess resume           # Resume post-processing

RSS feed automation

sabx rss list                           # List configured feeds
sabx rss add TVFeed --url <rss-url> --cat tv
sabx rss run TVFeed                     # Manually trigger specific feed
sabx rss run                            # Run all feeds
sabx rss delete TVFeed

Scheduler tasks

sabx schedule list
sabx schedule add NightPause --set command=pause --set day=mon-sun --set hour=01 --set min=00
sabx schedule set NightPause --set hour=02
sabx schedule delete NightPause

Server management

sabx server list                  # News servers
sabx server stats                 # Per-server statistics
sabx server test primary          # Test connectivity
sabx server disconnect            # Disconnect from all servers

Troubleshooting

sabx doctor                       # Health checks
sabx warnings list                # Runtime warnings
sabx logs list --lines 50         # Recent logs
sabx logs tail --follow           # Stream logs
sabx debug gc-stats               # GC diagnostics

Output Modes

All commands support --json for scripting:

sabx queue list --json | jq '.slots[0].filename'
sabx speed status --json

Configuration

# Multiple profiles
sabx login --profile home --base-url http://home:8080 --api-key <key>
sabx login --profile server --base-url http://server:8080 --api-key <key>

# Switch profiles
sabx --profile server queue list

# Environment overrides
SABX_BASE_URL=http://alt:8080 SABX_API_KEY=xxx sabx status

Troubleshooting

Connection refused

• Verify SABnzbd is running: check the web UI at the configured base URL
• Re-run sabx login if the base URL changed
• Check firewall rules if connecting to a remote instance

Authentication failed

• Re-authenticate: sabx login --base-url <url> --api-key <key>
• API key may have been regenerated in SABnzbd settings
• Try sabx status to test connectivity

NZO ID not found

• The item may have been removed from queue or completed to history
• Re-check with sabx queue list or sabx history list
• NZO IDs change if SABnzbd is restarted

Rate limit / timeout

• SABnzbd may be busy with post-processing; wait and retry
• Check sabx status --full --performance for system load
• Reduce concurrent operations if running batch commands

References

• Full command reference: See references/commands.md