Tsarr

TypeScript-arr (pronounced "Tsar" /tsɑr/ - a Slavic king/emperor)

Type-safe TypeScript SDK and CLI for Servarr APIs (Radarr, Sonarr, etc.)

Tsarr provides type-safe TypeScript clients and a CLI for all Servarr APIs, generated from their Swagger/OpenAPI specifications. Use it as an SDK in your code or as a standalone CLI tool.

Features

• 🛡️ Type-safe - Generated from official Swagger/OpenAPI specs
• ⚡ Universal - Works with Node.js, Bun, and as standalone binaries
• 📦 Modular - Separate clients for each Servarr app
• 💻 CLI included - Manage all Servarr apps from the terminal
• 🚀 Multi-platform - Available via npm, Homebrew, Docker, Scoop, Chocolatey, AUR, Nix, and pre-built binaries

Supported Servarr Apps

• Radarr - Movie collection manager
• Sonarr - TV series collection manager
• Lidarr - Music collection manager
• Readarr - Book collection manager
• Prowlarr - Indexer manager
• Bazarr - Subtitle manager

Installation

npm / Node.js

# As a dependency (SDK)
npm install tsarr

# As a global CLI
npm install -g tsarr

# Or run directly without installing
npx tsarr doctor

Bun

bun add tsarr
bun add -g tsarr
bunx tsarr doctor

Homebrew (macOS / Linux)

brew install robbeverhelst/tsarr/tsarr

Pre-built Binaries

Download standalone binaries from GitHub Releases — no runtime needed:

| Platform | Download | |---|---| | macOS (Apple Silicon) | tsarr-darwin-arm64 | | macOS (Intel) | tsarr-darwin-x64 | | Linux (x64) | tsarr-linux-x64 | | Linux (arm64) | tsarr-linux-arm64 | | Windows (x64) | tsarr-windows-x64.exe |

# Example: Linux x64
curl -L https://github.com/robbeverhelst/tsarr/releases/latest/download/tsarr-linux-x64 -o tsarr
chmod +x tsarr
sudo mv tsarr /usr/local/bin/

Docker

docker run --rm ghcr.io/robbeverhelst/tsarr doctor
docker run --rm -v ~/.config/tsarr:/root/.config/tsarr ghcr.io/robbeverhelst/tsarr radarr movie list

Scoop (Windows)

Note: Requires adding the tsarr bucket first.

scoop bucket add tsarr https://github.com/robbeverhelst/scoop-tsarr
scoop install tsarr

Chocolatey (Windows)

Note: Chocolatey packaging is prepared but may still be pending moderation. See docs/distribution.md.

choco install tsarr

AUR (Arch Linux)

yay -S tsarr-bin

Nix

Install the repo flake directly:

nix profile install github:robbeverhelst/tsarr?dir=packaging/nix
# or run it without installing
nix run github:robbeverhelst/tsarr?dir=packaging/nix -- doctor

The committed flake under packaging/nix/flake.nix tracks the latest published release. Shared nixpkgs distribution still requires a maintainer submission. See docs/distribution.md for the full distribution flow.

CLI

Setup

# Interactive setup wizard
tsarr config init

# Or configure manually
tsarr config set services.radarr.baseUrl http://localhost:7878
tsarr config set services.radarr.apiKey your-api-key

# Or use environment variables
export TSARR_RADARR_URL=http://localhost:7878
export TSARR_RADARR_API_KEY=your-api-key

Config is stored in ~/.config/tsarr/config.json (global) or .tsarr.json (local project). Environment variables take priority over config files.

Usage

tsarr <service> <resource> <action> [options]

# Examples
tsarr radarr movie list
tsarr radarr movie search --term "Interstellar"
tsarr sonarr series list
tsarr prowlarr indexer list
tsarr lidarr artist search --term "Radiohead"

# Output formats
tsarr radarr movie list --table    # Table (default in terminal)
tsarr radarr movie list --json     # JSON (default when piped)
tsarr radarr movie list --quiet    # IDs only

# Diagnostics
tsarr doctor                       # Test all configured connections

# Shell completions
tsarr completions bash >> ~/.bashrc
tsarr completions zsh >> ~/.zshrc
tsarr completions fish > ~/.config/fish/completions/tsarr.fish

Available Commands

| Service | Resources | |---------|-----------| | radarr | movie, profile, tag, queue, rootfolder, system, history, customformat | | sonarr | series, episode, profile, tag, rootfolder, system | | lidarr | artist, album, profile, tag, rootfolder, system | | readarr | author, book, profile, tag, rootfolder, system | | prowlarr | indexer, search, app, tag, system | | bazarr | series, movie, episode, provider, language, system |

See the CLI Guide for full documentation including all commands, scripting examples, and shell completions.

SDK

Quick Start

import { RadarrClient, SonarrClient, LidarrClient } from 'tsarr';

const radarr = new RadarrClient({
  baseUrl: 'http://localhost:7878',
  apiKey: 'your-api-key'
});

// Type-safe API calls
const movies = await radarr.getMovies();
const status = await radarr.getSystemStatus();

Modular Imports

// Import only what you need
import { RadarrClient } from 'tsarr/radarr';
import { SonarrClient } from 'tsarr/sonarr';
import type { MovieResource } from 'tsarr/radarr/types';

Development

Install dependencies:

bun install

Run development server:

bun run dev

Build the project:

bun run build

Lint and format:

bun run lint
bun run format

📖 Documentation

• CLI Guide - Complete CLI documentation with all commands and scripting examples
• SDK Usage Guide - SDK usage documentation with examples
• API Documentation - Auto-generated TypeScript API docs
• Examples - Real-world automation examples
• Examples Directory - Runnable example scripts

Use Cases

Perfect for building:

• Automation scripts - Bulk movie imports, library maintenance, and media organization
• Management tools - Custom dashboards, backup utilities, and monitoring scripts
• Integration scripts - Connect Servarr apps with other services and workflows
• CLI usage - Manage your media servers directly from the terminal

Contributing

This project uses:

• Bun as the JavaScript runtime
• Biome for linting and formatting
• @hey-api/openapi-ts for code generation
• Renovate for dependency updates

License

MIT - see LICENSE file for details.