sabx
A batteries-included SABnzbd CLI and automation toolkit inspired by modern OSS CLIs like gh and chezmoi.
sabx mirrors the complete SABnzbd surface area—queue control, RSS management, scheduler, configuration, and server administration—in a fast Go binary designed for power users and automation.
Highlights
- Full parity with SABnzbd REST API: queue history, RSS CRUD, scheduler, server actions, priorities, speed limits, and diagnostics.
- First-class UX: human-readable tables by default,
--json for scripting, shell completions, and keyring-backed credential storage.
- Agent-friendly: deterministic output, idempotent commands, and profile-aware configuration ideal for CI/CD or LLM agents.
Installation
# Go 1.24+
go install github.com/avivsinai/sabx/cmd/sabx@latest
# Build from source
git clone https://github.com/avivsinai/sabx.git
cd sabx
go build ./cmd/sabx
./sabx --help
Pre-built archives, Homebrew, Scoop, winget manifests, and multi-arch Docker images are produced via GoReleaser on tagged releases.
Quickstart
# Authenticate with a SABnzbd instance (stores API key in OS keyring)
sabx login --base-url http://localhost:8080 --api-key <key>
# Inspect the active queue
sabx queue list --active
# Review full system diagnostics
sabx status --full --performance
# Check runtime warnings and logs
sabx warnings list
sabx logs list --lines 50
# Inspect live speed state for scripting
sabx speed status --json
# Pause post-processing while troubleshooting
sabx postprocess pause
# Test a news server definition
sabx server test primary
# Force-prioritize a download
sabx queue item priority <nzo_id> 2
# Explore SAB host filesystem and watched folder automation
sabx browse / --files --json
sabx watched scan --json
# Reset quota counters safely
sabx quota reset
# Smoke-test notifications and sort helpers
sabx notifications test email --json
sabx debug eval-sort "%sn - S%0sE%0e" --job "Example.Show" --json
# Manage RSS feeds
sabx rss add TVFeed --url https://example.org/rss --cat tv
sabx rss run TVFeed
# Update scheduler to pause nightly
sabx schedule set NightPause --set command=pause --set day=mon-sun --set hour=01 --set min=00
# Launch the live dashboard
sabx top
Configuration & Profiles
- Config file:
config.yml under $SABX_CONFIG_DIR (defaults to ~/Library/Application Support/sabx/ on macOS, %APPDATA%\sabx\ on Windows, ~/.config/sabx/ on Linux). Writes use atomic swaps with 0o700 directory perms.
- Credentials stored in macOS Keychain / Windows Credential Manager / GNOME Keyring via
github.com/99designs/keyring. Opt into encrypted file fallback with --allow-insecure-store (or SABX_ALLOW_INSECURE_STORE=1) and plaintext config storage with --store-in-config.
- Override per invocation with
--profile, --base-url, --api-key, or env vars SABX_BASE_URL, SABX_API_KEY.
Command Reference
Run sabx <command> --help for details. Key groups mirror the SABnzbd UI:
queue: add, prioritize, move, purge, and edit job metadata.history: filter, delete, and retry completed jobs.rss, categories, schedule: full CRUD against named config sections.config: generic get, set, and delete for any SABnzbd config section.server: list, inspect stats, connectivity test, disconnect/unblock, restart/shutdown.postprocess: pause/resume global PP or cancel specific NZO IDs.speed: view current speed (status) and adjust the global limit.browse: inspect SABnzbd-side filesystem paths.watched: trigger watched-folder rescans.quota: reset download quota counters.notifications: run email/pushover/desktop test hooks.debug: fetch GC stats or evaluate sort expressions.translate: resolve SABnzbd UI translation keys.warnings: list and clear SABnzbd runtime warnings.logs: fetch sanitized SABnzbd logs (list, tail with optional follow).scripts: inspect available post-processing scripts.dump: export sanitized configuration or live state snapshots.top: Bubble Tea dashboard for real-time queue and history monitoring.extension: install/list/remove sabx-<name> extensions (GitHub repos or local).doctor: connectivity & health checks.
API Parity Checklist