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

Smoke Tests

Use the bundled harness to exercise the tricky endpoints against a live SABnzbd instance and capture fixtures for regression testing:

scripts/run-smoke.sh --base-url http://localhost:8080 --api-key $SAB_API_KEY --output testdata/smoke/latest

The script builds sabx, runs a curated set of commands (browse, notifications test, debug eval-sort, status orphans, watched scan, etc.), validates JSON, and writes sanitized outputs to testdata/smoke/<command>.json plus an aggregated report.json. Review the artifacts before committing to avoid leaking instance-specific secrets.

Development

# Format & vet
go fmt ./...
go test ./...

# End-to-end smoke (requires Docker)
go test ./test/e2e -run TestSmokeAgainstSABContainer -count=1

# Run the CLI locally
./sabx status

See AGENTS.md for deeper contributor guidance, including architecture notes and testing tips. Release automation and tagging instructions live in docs/RELEASING.md.

Set SABX_E2E_DISABLE=1 to skip container-based smoke tests when Docker is unavailable.

Extensions

• Install from GitHub: sabx extension install avivsinai/sabx-tv-tools
• Execute: once installed, run sabx tv-tools ... and the CLI will forward arguments to the sabx-tv-tools binary/script.
• List or remove extensions with sabx extension list and sabx extension remove <name>.

Extensions live under ~/.sabx/extensions and can also be distributed by placing sabx-<name> executables on PATH.

Claude Code Skill

The sabx skill teaches Claude Code (and Codex CLI) how to use sabx commands effectively.

Via [skills](https://github.com/vercel-labs/add-skill) (recommended):

npx skills add avivsinai/sabx -g -y

Via [skild](https://skild.sh):

npx skild install @avivsinai/sabx -t claude -y