unarr

⚠️ Beta — unarr is under active development. Features may change, and bugs are expected. Report issues here.

Powerful terminal tool for torrent search and management. Free and open source.

Search 30+ torrent sources, inspect torrent quality, discover popular content, find streaming providers, and manage your media collection — all from your terminal.

Installation

Quick install (Linux/macOS)

curl -fsSL https://get.torrentclaw.com/install.sh | sh

PowerShell (Windows)

irm https://get.torrentclaw.com/install.ps1 | iex

Homebrew (macOS/Linux)

brew install torrentclaw/tap/unarr

Docker

docker run -d --name unarr \
  --restart unless-stopped \
  --network host \
  --read-only --memory 512m \
  -v ~/.config/torrentclaw:/config \
  -v ~/Media:/downloads \
  torrentclaw/unarr

Run setup first to configure your API key:

docker run -it --rm \
  -v ~/.config/torrentclaw:/config \
  torrentclaw/unarr setup

Docker Compose

mkdir -p torrentclaw && cd torrentclaw
curl -fsSL https://raw.githubusercontent.com/torrentclaw/unarr/main/docker-compose.yml -o docker-compose.yml
docker compose up -d

docker-compose.yml

services:
  unarr:
    image: torrentclaw/unarr:latest
    container_name: unarr
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs:
      - /tmp:size=64m,mode=1777
    volumes:
      - ./config:/config
      - ~/Media:/downloads
      - unarr-data:/data
    environment:
      - TZ=${TZ:-UTC}
      # - UNARR_API_KEY=tc_your_key_here
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "2.0"
    # Host network for full P2P performance
    network_mode: host
    # Or use bridge with ports:
    # ports:
    #   - "6881-6889:6881-6889/tcp"
    #   - "6881-6889:6881-6889/udp"

volumes:
  unarr-data:

Go install

go install github.com/torrentclaw/unarr/cmd/unarr@latest

GitHub Releases

Download prebuilt binaries for Linux, macOS, and Windows from GitHub Releases.

Build from source

git clone https://github.com/torrentclaw/unarr.git
cd unarr
make build

Quick Start

# 1. Run the init wizard (opens browser for API key)
unarr init

# 2. Search for content
unarr search "breaking bad" --type show --quality 1080p

# 3. Start the download daemon
unarr start

Commands

Getting Started

Command	Description
unarr init	First-time configuration wizard (API key, download dir, daemon)
unarr config	Edit all settings interactively (speed, organization, etc.)
unarr migrate	Import settings and wanted list from Sonarr/Radarr/Prowlarr [pre-beta]

Search & Discovery

Command	Description
unarr search <query>	Search for movies and TV shows with advanced filters
unarr inspect <magnet|hash|name>	TrueSpec analysis — quality, codec, seed health
unarr popular	Show popular movies and TV shows
unarr recent	Show recently added content
unarr watch <query>	Find where to watch — streaming + torrents

Downloads & Streaming

Command	Description
unarr download <hash|magnet>	One-shot download (no daemon needed)
unarr stream <hash|magnet>	Stream a torrent directly to mpv/vlc/browser

Daemon Management

Command	Description
unarr start	Start the download daemon (foreground)
unarr stop	How to stop the running daemon
unarr status	Show daemon status and active downloads
unarr daemon install	Install as system service (systemd/launchd)
unarr daemon uninstall	Remove the system service
unarr vpn status	Show managed-VPN config and live tunnel state
unarr vpn enable	Turn the managed VPN on
unarr vpn disable	Turn the managed VPN off

System & Diagnostics

Command	Description
unarr stats	Show catalog statistics
unarr doctor	Diagnose configuration and connectivity
unarr clean	Remove temporary files, logs, and cached data
unarr self-update	Update unarr to the latest version
unarr version	Show version info
unarr completion <shell>	Generate shell completion scripts

---

Search

Search the catalog with advanced filters. Results include quality scores, seed health, and metadata from 30+ sources.

unarr search "inception" --sort seeders --min-rating 7 --lang es
unarr search "breaking bad" --type show --quality 1080p
unarr search "matrix" --json | jq '.results[].title'

Filters:

Flag	Description	Values
--type	Content type	movie, show
--quality	Video quality	480p, 720p, 1080p, 2160p
--lang	Audio language (ISO 639)	es, en, fr, de, ...
--genre	Genre	Action, Comedy, Drama, Horror, ...
--year-min	Minimum release year	2020
--year-max	Maximum release year	2026
--min-rating	Minimum IMDb/TMDb rating	0-10
--sort	Sort order	relevance, seeders, year, rating, added
--limit	Results per page	1-50
--page	Page number	1, 2, ...
--country	Country for streaming info	US, ES, GB, ...

Inspect

TrueSpec analysis — parse a torrent and show detailed quality specs.

unarr inspect "Oppenheimer.2023.1080p.BluRay.x265"
unarr inspect abc123def456abc123def456abc123def456abc1
unarr inspect "magnet:?xt=urn:btih:ABC123&dn=Movie.2023.1080p"

Accepts magnet URIs, 40-character info hashes, or torrent file names. Shows quality, codec, size, seeds, languages, source, quality score, health, and alternatives.

Watch

Find where to watch — streaming services alongside torrent options.

unarr watch "oppenheimer" --country ES
unarr watch "breaking bad" --json

Shows legal streaming options first (subscription, free, rent, buy), then torrent alternatives.

Stream

Stream a torrent directly to a media player without waiting for the full download.

unarr stream abc123def456abc123def456abc123def456abc1
unarr stream "magnet:?xt=urn:btih:..." --port 8080
unarr stream <hash> --player mpv
unarr stream <hash> --no-open   # just print the URL

Downloads pieces sequentially and serves the video over a local HTTP server. Auto-detects mpv, vlc, or your default browser.

Download

One-shot download by info hash or magnet link (no daemon required).

unarr download abc123def456abc123def456abc123def456abc1
unarr download "magnet:?xt=urn:btih:..." --method torrent

Daemon

The daemon receives download tasks from the web dashboard and executes them automatically.

# Start in foreground (Ctrl+C to stop)
unarr start

# Or install as a system service (auto-starts on boot)
unarr daemon install

# Check status
unarr status

# Uninstall the service
unarr daemon uninstall

The daemon connects via WebSocket for instant task delivery, with automatic HTTP fallback. It supports torrent, debrid, and usenet downloads concurrently, reports progress to the web dashboard, and handles graceful shutdown.

Service locations:

• Linux: ~/.config/systemd/user/unarr.service (systemd)
• macOS: ~/Library/LaunchAgents/com.torrentclaw.unarr.plist (launchd)

VPN

unarr can route your downloads through a managed WireGuard VPN, so peers and trackers see the VPN server's IP instead of yours. It runs entirely in userspace (wireguard-go + a gVisor netstack) — no root, no wg-quick, no changes to your OS routing table.

Requires a PRO+ plan with the VPN add-on. Set it up at torrentclaw.com/vpn.

# Turn it on (writes [downloads.vpn] enabled = true to your config)
unarr vpn enable

# Restart the daemon so it brings the tunnel up at startup
unarr daemon restart        # or: unarr start (if not installed as a service)

# Check it's working — shows the exit server when the tunnel is up
unarr vpn status

# Verify your account is provisioned (queries the API)
unarr vpn status --check

# Turn it off again
unarr vpn disable

Split-tunnel — read this: only the torrent client's traffic goes through the VPN. Your browser, curl, and every other app keep using your real IP — that is by design. To check the VPN is working, look at unarr vpn status (or the peer/announce IP), not your browser's "what's my IP". To protect your other devices (phone, laptop), use the OpenVPN credentials from your profile — those support ~10 concurrent devices and do not share the agent's WireGuard slot.

When does it fetch the config? Once, at daemon startup. There's no periodic refresh — after changing your exit server in the web panel or re-provisioning, restart the daemon to pick it up. If the fetch fails the daemon logs a [vpn] line and downloads in the clear (never refuses to run).

Self-hosted / personal VPN: instead of the managed config, point unarr at a local WireGuard .conf:

[downloads.vpn]
config_file = "/path/to/wg.conf"   # takes precedence over `enabled`

Diagnostics

# Run all diagnostic checks
unarr doctor

# Update to the latest version
unarr self-update
unarr self-update --force   # reinstall even if up to date

unarr doctor checks: config file, API key, server connectivity (with latency), agent registration, download directory, disk space, and version.

Clean

Remove temporary files, logs, resume data, and other artifacts generated by unarr. Shows what will be removed and asks for confirmation before deleting.

unarr clean            # Show files and confirm before removing
unarr clean --dry-run  # Show what would be removed (no prompt)
unarr clean --yes      # Skip confirmation
unarr clean --all      # Also remove the data directory

Cleans: log files, daemon state, stale usenet resume files (> 7 days), stream temp data, upgrade temp files, and stale atomic-write temps. Recent resume files are kept to preserve download progress for paused or interrupted downloads. Never removes your config file, downloaded media, or partial torrent/debrid downloads.

Alias (optional)

Create a shell alias for shorter commands:

# Add to ~/.bashrc or ~/.zshrc
alias un=unarr

# Then use:
un search "breaking bad" --type show
un popular --limit 5
un start

Global Flags

Flag	Description
--json	Output as JSON (for piping to jq, scripts)
--no-color	Disable colored output
--api-key	API key (overrides config file and env)
--config	Custom config file path

JSON Output

All query commands support --json for scripting:

# Pipe to jq
unarr search "matrix" --json | jq '.results[].title'

# Save to file
unarr popular --json > popular.json

# Use in scripts
SEEDS=$(unarr search "inception" --json | jq '.results[0].torrents[0].seeders')

Configuration

Config file

Location: ~/.config/unarr/config.toml

[auth]
api_key = "tc_your_api_key_here"
api_url = "https://torrentclaw.com"

[agent]
id = "auto-generated-uuid"
name = "My PC"

[downloads]
dir = "~/Media"
preferred_method = "auto"        # auto | torrent | debrid | usenet
max_concurrent = 3
max_download_speed = "0"         # e.g. "10MB", "500KB", "0" = unlimited
max_upload_speed = "0"

[organize]
enabled = true
movies_dir = "~/Media/Movies"
tv_shows_dir = "~/Media/TV Shows"

[daemon]
poll_interval = "30s"
heartbeat_interval = "30s"

[notifications]
enabled = true

[general]
country = "US"

Streaming reference

The in-browser player on torrentclaw.com streams from the daemon over WebRTC (low-latency P2P) or HLS (HTTP fragments + ffmpeg transcode for codecs the browser can't decode natively). Both are enabled by default — a fresh install "just works" without editing the TOML. Disable surgically only if you have a reason.

[downloads.webrtc]
enabled       = true                                    # master switch
trackers      = ["wss://tracker.torrentclaw.com"]      # signaling trackers
stun_servers  = [                                       # NAT traversal
  "stun:stun.l.google.com:19302",
  "stun:stun1.l.google.com:19302",
]
turn_servers  = []                                      # optional TURN relays
turn_user     = ""
turn_pass     = ""

[downloads.transcode]
enabled        = true        # master switch
hw_accel       = "auto"      # auto | none | nvenc | qsv | vaapi | videotoolbox
preset         = "veryfast"  # libx264 preset
video_bitrate  = ""          # e.g. "5M" caps -b:v; empty = engine fallback (5M)
audio_bitrate  = "192k"      # e.g. "128k", "192k", "256k"
max_height     = 0           # 0 = no cap; e.g. 720 forces 720p max
max_concurrent = 2           # max simultaneous ffmpeg processes

[downloads.webrtc]

Key	Type	Default	Notes
enabled	bool	true	Browser↔daemon WebRTC peer for the in-browser P2P player. Disable to skip WebRTC tracker signalling (saves ~5MB RAM, blocks WebRTC streaming — HLS still works).
trackers	[]string	["wss://tracker.torrentclaw.com"]	Signaling trackers for peer discovery.
stun_servers	[]string	Google public STUN ×2	ICE candidate gathering.
turn_servers	[]string	[]	Optional TURN relays for symmetric-NAT users.
turn_user / turn_pass	string	""	Credentials for authed TURN servers. Applied to all turn_servers.

[downloads.transcode]

Key	Type	Default	Notes
enabled	bool	true	Real-time HLS transcoding when source codec is browser-incompatible (HEVC, AV1, AC3, DTS). Requires ffmpeg + ffprobe on PATH.
hw_accel	string	"auto"	Hardware accel: "auto", "none", "nvenc" (NVIDIA), "qsv" (Intel), "vaapi" (Linux), "videotoolbox" (macOS).
preset	string	"veryfast"	libx264 preset. Slower preset = smaller files but higher CPU. Options: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow.
video_bitrate	string	""	E.g. "5M" caps -b:v. Empty falls back to the engine default (5M).
audio_bitrate	string	"192k"	E.g. "128k", "256k".
max_height	int	0	0 = no cap. E.g. 720 forces 720p max — useful on weak GPUs.
max_concurrent	int	2	Max simultaneous ffmpeg processes. Increase if hosting multiple users on a beefy box.

If transcode.enabled = true but ffmpeg / ffprobe aren't on PATH, the daemon logs a warning at startup and HLS sessions are rejected at runtime with a clear error — install ffmpeg or set enabled = false.

[downloads.vpn]

Key	Type	Default	Notes
enabled	bool	false	Managed VPN: at startup the daemon fetches a WireGuard config from your account and split-tunnels torrent traffic through it. Needs a PRO+ plan with the VPN add-on. Toggle with unarr vpn enable / disable.
config_file	string	""	Self-hosted / personal VPN: path to a local WireGuard .conf. Takes precedence over enabled — when set, the daemon uses this file and never calls the API.

See the VPN section above for how it works (split-tunnel, no root) and how to protect your other devices.

Environment variables

Environment variables override config file values:

export UNARR_API_KEY=tc_your_api_key
export UNARR_API_URL=https://torrentclaw.com
export UNARR_COUNTRY=ES
export UNARR_DOWNLOAD_DIR=~/Media

Speed limits

Speed limits use human-readable format:

max_download_speed = "10MB"    # 10 megabytes/sec
max_upload_speed = "1MB"       # 1 megabyte/sec
max_download_speed = "500KB"   # 500 kilobytes/sec
max_download_speed = "0"       # unlimited (default)

Shell Completion

Generate tab-completion scripts for your shell:

# Bash — add to ~/.bashrc
eval "$(unarr completion bash)"

# Zsh — add to ~/.zshrc
eval "$(unarr completion zsh)"

# Fish
unarr completion fish > ~/.config/fish/completions/unarr.fish

# PowerShell — add to $PROFILE
unarr completion powershell >> $PROFILE

Completions provide tab-completion for commands, flags, and flag values (e.g. --type <Tab> shows movie and show).

Coming Soon

These commands are planned for future releases:

Command	Description
unarr upgrade	Find a better version of a torrent
unarr moreseed	Find same quality with more seeders
unarr compare	Compare two torrents side by side
unarr scan	Scan your media library for upgrades
unarr add	Search and add torrents to your client
unarr monitor	Watch for new episodes of a series
unarr open	Open content in the browser

Contributing

See CONTRIBUTING.md for development setup, code style, and guidelines.

License

MIT License — see LICENSE for details.