unarr

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

The single-binary terminal client for torrent, debrid, and usenet downloads. Free and open source.

Built-in torrent engine, debrid (Real-Debrid / AllDebrid), and NZB support. Stream to mpv/vlc, transcode on the fly with hardware acceleration, and manage your library — one binary or a headless daemon with WireGuard split-tunnel and Cloudflare Funnel remote access.

Installation

Quick install (Linux/macOS)

curl -fsSL https://unarr.app/install.sh | sh

PowerShell (Windows)

irm https://unarr.app/install.ps1 | iex

Homebrew (macOS/Linux) — coming soon

brew install unarr-app/tap/unarr

Debian/Ubuntu (.deb) and Fedora/RHEL (.rpm)

Published on every release for amd64 and arm64, and covered by the same signed checksums.txt as the tarballs:

# Debian/Ubuntu — replace <version> and <arch> (amd64 | arm64)
curl -fsSLO https://github.com/Unarr-app/unarr-cli/releases/latest/download/unarr_<version>_linux_<arch>.deb
sudo apt install ./unarr_<version>_linux_<arch>.deb

# Fedora/RHEL
sudo dnf install https://github.com/Unarr-app/unarr-cli/releases/latest/download/unarr_<version>_linux_<arch>.rpm

The package installs the unarr binary only. Run unarr init afterwards to link your account, pick a download directory and install the background service — the same step the other install methods end with. ffmpeg is a recommended dependency; without it the agent downloads its own static copy.

Docker

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

Run setup first to configure your API key:

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

Docker Compose

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

services:
  unarr:
    image: unarr/cli: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/Unarr-app/unarr-cli/cmd/unarr@latest

GitHub Releases

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

Build from source

git clone https://github.com/Unarr-app/unarr-cli.git
cd unarr-cli
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 login	Authenticate with your account (opens browser)
unarr config	Edit all settings interactively (speed, organization, etc.)
unarr config check	Validate config.toml — unknown keys (with suggestions) and out-of-range values; exits non-zero when anything is reported, or with the daemon's own error when the file does not load at all (invalid TOML, a value of the wrong type)
unarr config mount	Configure the optional local mount; provider accounts and credentials are managed on the web
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 downloads	List the download queue (alias: unarr dl)
unarr downloads pause|resume <id>	Pause a download / continue it
unarr downloads stop <id>	Cancel it and stop it coming back after a restart
unarr downloads retry <id>	Start it over
unarr downloads purge	Forget queued downloads that are not running
unarr stream <hash|magnet>	Stream a torrent directly to mpv/vlc/browser
unarr mount <directory>	Configure and activate the persistent read-only remote folder (directory is optional)
unarr umount	Disable and unmount the remote folder (unarr unmount is an alias)
unarr mount serve	Serve that remote library over loopback WebDAV without mounting it

See Controlling downloads for the flags, the offline recovery path, and how these interact with the website.

Library

Command	Description
unarr scan <path>	Scan a folder, analyze video files with ffprobe, sync quality data
unarr library clean	Sweep download & library dirs for orphaned files (dry-run by default)
unarr library stats	Report library health, composition & quality — read-only (--json for scripts)
unarr organize preview	Show the folders/file names new downloads get with your naming layout (or try --naming plex, --series-format …) — touches nothing

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 (--sessions for live sessions, --json for raw)
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 report	Prepare and review private technical events; save locally or separately consent to upload (alias: unarr reports). See privacy and delivery availability.
unarr mirrors	Manage mirror failover list (list / update / test)
unarr logs	Read the daemon log — -f, --since, --level, --grep, -n (alias: unarr daemon logs)
unarr clean	Remove temporary files, logs, and cached data
unarr backup	Back up / restore config and the download queue (create / list / restore / prune). See Backup
unarr upgrade	Update unarr to the latest version (alias: unarr self-update)
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.

Subtitles. When the source file contains embedded text subtitles (SRT, ASS, PGS in an MKV), the daemon extracts them as WebVTT sidecars during the same transcode pass and serves them alongside the HLS stream. The web player lists available subtitle tracks automatically — no separate subtitle download needed.

Seek-anywhere (copy-VOD). For sources with browser-compatible codecs (H.264 + AAC), the daemon uses a copy pass instead of re-encoding. This enables full random-seek across the entire duration from the first play, at near-zero CPU cost.

Audio tracks. Multi-audio MKVs expose all tracks (e.g. fr, en, es) in the player's audio menu. Switching tracks starts a new session from the current position.

Download

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

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

Controlling downloads

unarr downloads lists and controls whatever the daemon on this machine is working on. It talks to the daemon directly over loopback — no website, no account lookup — so it keeps working when the server is unreachable or the download has fallen out of the dashboard.

unarr downloads                      # what is running right now (alias: unarr dl)
unarr downloads pause                # menu: tick what to pause
unarr downloads stop                 # menu: tick what to stop
unarr downloads pause --all          # pause everything
unarr downloads stop --all           # stop everything (asks to confirm)
unarr downloads pause 31ec4169       # or name it directly
unarr downloads resume 31ec4169      # continue where it left off
unarr downloads stop 31ec4169 --delete   # cancel and delete the partial file
unarr downloads retry 31ec4169       # start it over
unarr downloads purge                # forget queued leftovers
unarr downloads --json               # machine-readable, for scripts

Run an action with no id and you get a menu of the downloads it can apply to — space to tick, enter to confirm, esc to cancel. Only the relevant ones are listed: pause shows what is running, resume shows what is not.

Ids may be abbreviated to any unique prefix — the 8-character ids printed here and in the logs are enough. An ambiguous prefix is refused rather than guessed.

Two actions ask before they run: --delete (files leave the disk) and stop --all (nothing resumes by itself afterwards). --yes skips the question, and in a script or a pipe — where there is no terminal to answer on — the command refuses instead of hanging.

unarr download stop|pause|resume|retry|list|purge works too, as an alias.

Actions reach the website. Whatever you do here (or from the desktop tray) is reported to unarr.app, so the dashboard reflects it within a few seconds instead of showing a download that stopped minutes ago. It works the other way round as well: cancelling on the website stops the download on this machine.

When a download will not stop

If a download survives cancelling on the website, its task row is gone — you cancelled it and then removed it from the list — so the server has no way left to reach the agent, while the agent keeps restarting it from its resume queue on every launch.

The agent now detects this by itself: a task the server no longer knows about is dropped after a few status reports. To end it immediately:

unarr downloads stop <id>   # daemon running

With the daemon stopped, --force edits the on-disk resume queue instead — the file that would otherwise bring the download back:

unarr downloads                 # lists the queue even with no daemon
unarr downloads stop <id> --force
unarr downloads purge --force   # clear the whole queue

The queue lives at active-tasks.json in the data dir (~/.local/share/unarr/ on Linux, ~/Library/Application Support/unarr/ on macOS, %LOCALAPPDATA%\unarr\ on Windows). Deleting it only forgets pending downloads — media files and config are untouched.

From the desktop tray

unarr-desktop lists the active downloads in its menu with Pause / Resume / Stop / Stop and delete files under each one. Same control plane, same reporting back to the website. Beyond five downloads the menu points at unarr downloads, which has no limit.

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)

Metrics

The daemon keeps one view of everything that is moving right now — downloads, in-browser HLS streams and the remote-folder mount — with each session's rate, bytes moved, uptime, health (ok / degraded / stalled) and stall count.

unarr status --sessions          # table
unarr status --sessions --json   # the same snapshot the website reads

--json only changes --sessions: a plain unarr status --json still prints the usual text status.

A session is degraded as soon as it is impaired (a download receiving no data, a transcode below realtime, a mount read that moves no bytes) and stalled once that lasts 30 s. Each stall is counted once, not once per check, and it only ends after 10 s of healthy flow, so a rate flapping around the threshold is one stall.

Publishing to the web

The daemon sends that same snapshot to your unarr account, so the website's sessions page can show it. It is on by default and does not depend on the Prometheus switch below.

[metrics]
publish = false   # stop sending the session snapshot to the web

• Cadence: every 5 s while at least one session exists. When the last one ends, one empty snapshot is sent, then one every 30 s as a heartbeat. Stopping the daemon sends one last empty snapshot (waiting at most 2 s for it), so the website clears this machine's sessions straight away.
• What is sent: the unarr status --sessions --json document (see internal/metrics/SCHEMA.md) and the agent id: session kind, state, health, rates, bytes, progress, stall counts, the VPN state and the session titles — the release or file names of what the website already asked this machine to download or play. No file paths, IPs, tokens or URLs: a title that looks like an absolute path is cut to its last element, and one that looks like a URL is sent empty.
• Limits: at most 50 sessions and 64 KiB per snapshot; anything beyond that is dropped from the end of the list (the summary still counts it).
• Failures never hold up the daemon: one request at a time on its own goroutine, 5 s timeout, nothing queued — a snapshot that does not arrive is replaced by the next one. A website that does not support it yet (HTTP 404) is asked again every 10 minutes, with one log line. Other errors are logged once per failure streak.
• Changing publish takes effect after unarr daemon restart.

Prometheus endpoint (optional)

Off by default: nothing listens until you opt in.

[metrics]
enabled = true
# listen = "127.0.0.1:9877"   # default: loopback only
# token = "change-me"         # required if listen is not loopback

GET /metrics returns the Prometheus text format and always needs a token, sent as Authorization: Bearer <token> (or the X-Unarr-Control-Token header). With no token set, the control-plane token is used — it is in the daemon state file, but it changes on every restart, so for a Prometheus server set your own token. A non-loopback listen without a token is refused.

# prometheus.yml
scrape_configs:
  - job_name: unarr
    authorization: { credentials: change-me }
    static_configs: [{ targets: ["127.0.0.1:9877"] }]

Metric	Type	Labels
unarr_info	gauge	version
unarr_uptime_seconds	gauge
unarr_sessions_active	gauge	kind = download, hls, stream, mount
unarr_sessions_stalled	gauge
unarr_session_bytes_total	counter	kind
unarr_session_rate_bytes_per_second	gauge	kind
unarr_session_stalls_total	counter	kind
unarr_vpn_up, unarr_vpn_enabled, unarr_vpn_required	gauge
unarr_downloads	gauge	state (downloading, paused, …)

There are no per-title or per-hash labels, so cardinality stays fixed. The format is written by hand instead of pulling in client_golang, which would add several MB and a chain of dependencies to the binary for ten fixed series.

GET /sessions (local control plane)

The same snapshot is served to local tools (the website's unified view, the desktop tray) at GET /sessions on the loopback control plane, with the X-Unarr-Control-Token from the daemon state file. The JSON schema (schemaVersion 1) is documented in internal/metrics/SCHEMA.md.

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.

# 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.

Updating unarr

unarr supports three update paths. Pick whichever fits your workflow.

1. Manual self-update (always available).

unarr self-update                # interactive update to latest
unarr self-update --force        # reinstall same version
unarr self-update --allow-unsigned # accept releases without checksum signature

The CLI downloads the new release archive over HTTPS (from GitHub Releases at github.com/Unarr-app/unarr-cli/releases/download/v<ver>/, falling back to the web origin if GitHub is unreachable), verifies SHA-256, swaps the binary in place (.backup kept next to it), and restarts the systemd user unit if the daemon is running.

2. Auto-apply on server signal (default, since 0.9.6).

When you press "Force update now" on the web (Settings → Agent → Force update), the server sets a flag your daemon polls every sync (~3 s). On the next sync the daemon downloads the new binary, replaces itself, and exits — systemd Restart=always respawns on the new version. No SSH, no terminal access required. Works headless on NAS / Docker.

The button shows an amber warning if your agent is below 0.9.6 (older daemons see the signal but only log "run unarr update" — the operator must run the command manually that one time).

Opt out of auto-apply. Some users prefer reviewing CHANGELOG before applying. Disable in config.toml:

[daemon]
auto_upgrade = false

With auto_upgrade = false, pressing the web button still flags your agent (so the daemon logs the new version on next sync), but the daemon will not download / replace anything — you run unarr self-update when you're ready.

3. Docker auto-restart with a new tag.

docker pull unarr/cli:latest
docker compose up -d

Tags published: latest, 1.2, 1.2.2, ... — pin to a minor (1.2) for opt-in patch updates without surprises.

Logs

unarr logs                                  # last 50 lines
unarr logs -f                               # follow
unarr logs -n 200 --level warn              # only warnings and errors
unarr logs --since 2h --grep 'usenet|nzb'   # last 2 hours, matching a regex
unarr logs --since "2025-01-20 09:00" --level error
unarr logs --boot                           # startup output — when it won't start
unarr logs rotate                           # trim now, if rotation is on and over budget

unarr daemon logs is the same command (kept as an alias, -f / -n included). On Linux, where the systemd unit sends output to the journal, this streams from journalctl --user -u unarr instead of a file; everywhere else it reads unarr.log from the data directory and transparently continues into the rotated copies when the live file holds fewer lines than you asked for.

Severity is inferred from the line itself (the daemon logs free-form text), so --level is a reading aid, not a guarantee. --grep is a case-insensitive regular expression. --since takes an age (30m, 2h, 7d, 1w) or a stamp (2025-01-20, 2025-01-20 09:00, 09:00 for today).

Two files. A daemon started by a service launcher owns unarr.log and writes everything it logs there. The launcher itself captures a second, much smaller unarr.boot.log: the start banner, a fatal error from a start that never got going, a crash dump — output that never reaches the daemon's own log. unarr logs --boot reads it, and that is where to look when the daemon does not come up at all. On a systemd install there is no such file: the startup output is in the journal, so unarr logs already shows it and --boot says so.

On a systemd install, log_max_size_mb and log_max_files do nothing at all. The unit sends the daemon's output to the journal, so there is no unarr.log to rotate and retention is journald's business, not unarr's — set it in journald.conf (SystemMaxUse, MaxRetentionSec); the defaults are 10% of the filesystem, capped at 4 GB. Check what it currently costs with journalctl --user -u unarr --disk-usage. Setting log_max_size_mb = 1 there and expecting a bounded disk is the one misreading worth calling out: it bounds nothing. (unarr logs rotate is correspondingly a no-op that exits 0 — it will not conjure an empty unarr.log just to have something to rotate.)

Rotation is OPT-IN, and off by default (log_max_size_mb = 0). Out of the box unarr never rotates anything: unarr.log and unarr.boot.log just grow. Bound them with unarr clean, or with an external logrotate — and if you use one, it must use copytruncate, since the daemon holds its descriptor for the whole run and has no reopen signal.

Set log_max_size_mb to a number of MB to turn rotation on. unarr.log is then rotated once it reaches that size, keeping log_max_files copies (default 3), and unarr.boot.log gets its own fixed 2 MB cap with one rotated copy — independent of the size you set, but switched on by the same key. A running daemon rotates its own log by renaming it aside, so rotation does not wait for a restart; unarr logs rotate is for the case where the daemon is stopped, and it says so rather than doing nothing if a running daemon owns the file.

What you accept by turning it on. Rotation is not a solved problem here, and this is why it does not ship on. Any second process holding the log can block the rename or the truncate — an open unarr logs -f, an antivirus scanner, OneDrive or Dropbox syncing the data directory, Windows Search. Windows is the strict case: a holder there can deny write access outright, so a rotation that cannot proceed is reported and the log keeps growing. Residual failure modes that remain even when it does proceed (a reader holding a rotated slot, two rotators racing over one staging file, a live-but-offline daemon losing its ownership claim) are listed under "Deuda abierta" in docs/plans/daemon-log-ownership.md — read it before enabling this on an install you care about. On Windows only, the boot log's trim is baked into the launcher script at install time, so re-run unarr daemon install after enabling rotation for that one to take effect.

The global --log-level flag overrides [daemon] log_level for a single command.

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 (including the rotated unarr.log.1, .2, … copies), daemon state, stale usenet resume files (> 7 days), stale replaced-file backups (> 7 days, kept by library upgrades), 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.

Backup

Snapshot your local unarr state into one verified zip, and restore it later or on another machine.

unarr backup create                    # → <config dir>/backups/unarr-backup-<UTC stamp>.zip
unarr backup create --out ~/unarr.zip  # a file, or a directory
unarr backup create --encrypt          # passphrase-encrypted, secrets included
unarr backup list                      # tags [encrypted] [scheduled] [pre-restore]
unarr backup restore unarr.zip         # dry-run: verifies and shows what would change
unarr backup restore unarr.zip --apply # writes (daemon must be stopped)
unarr backup prune --keep 3            # drop all but the newest 3 manual/scheduled backups
unarr backup prune --pre-restore       # trim old pre-restore snapshots (newest 3 + last 30 days kept)

What is in it: config.toml and active-tasks.json (the download resume queue), plus a manifest.json (unarr version, schema, OS/arch, date, SHA-256 and size of every file). An archive holds up to 128 MiB of files (uncompressed, all together — some 150,000 queued tasks), of which config.toml may take at most 4 MiB and manifest.json 1 MiB (a real config is well under 100 KB). create checks those bounds, and that config.toml parses and the daemon can load the queue, before writing anything: it refuses an archive that restore would refuse, so every backup it writes can be restored. What is never in it: anything ephemeral or machine-bound — daemon.state.json (PID and the local control-plane token), unarr.lock, the agent TLS private key under certs/, logs, caches (including the library.json scan cache, rebuilt by a rescan), partial-download progress and your media.

Secrets — excluded by default. A plain archive is a file people copy to a NAS or a cloud folder, so it must be safe to lose. [auth] api_key, [agent] agent_hash and [downloads] webdav_username / webdav_password and [metrics] token are blanked in the copy of config.toml (the file stays valid TOML; your comments and layout are untouched) and resolved download URLs / NZB passwords are stripped from the queue. The result is checked by parsing it: if a credential is written in a form unarr cannot blank (a dotted key, an inline table, a multi-line string), the backup is refused rather than written with the secret inside — use --encrypt for such a config. Restoring a secret-free archive keeps the credentials already on the machine (the dry-run names any it cannot carry over; if the archive's auth.api_url or auth.mirrors would send them to a server this machine does not use, the dry-run and --apply warn — a warning, not a refusal, since pointing a machine at another server is legitimate; when this machine's own config.toml does not parse, so there is nothing to compare against, they say so and name the archive's auth.api_url and auth.mirrors the credentials will go to) and the [agent] id they belong to: when this machine already has an api_key or agent_hash, its own id stays instead of the archive's — even an empty one, in which case [agent] id is left empty rather than paired with credentials that are not its own — and both the dry-run and --apply say so (run unarr login if this is a new machine). On a machine with no credentials yet, the archive's id is restored; run unarr login afterwards. Debrid downloads in a restored queue have no link of their own and need a fresh one from the server. --encrypt is the opt-in for a full copy: the whole archive is sealed with AES-256-GCM using a key derived from your passphrase (PBKDF2-HMAC-SHA256, 600k rounds, random salt and nonce per archive — Go standard library only). The passphrase comes from a prompt, --passphrase-file, or UNARR_BACKUP_PASSPHRASE; an empty one is refused, and it cannot be recovered. VPN keys live in the .conf that [downloads.vpn] config_file points to; that file is not backed up.

Restore is safe by default. It refuses a bad manifest, a newer schema, any checksum mismatch, an archive or a file over its size bound, any archive member that is not one of the two known files (so a crafted ../ path cannot write elsewhere) or not a regular file (a symlink, a directory, a device), and content unarr could not load — a config.toml that does not parse the way unarr reads it (checked as it would be written, with this machine's credentials merged in) or a queue the daemon would drop on load (decoded with its own task type: one field of the wrong type, such as a queuedAt that is not a time, and it starts with an empty queue). Those checks run before anything is written or snapshotted. A restore is all or nothing: a queue an older unarr backed up that the daemon cannot load blocks the config.toml beside it too (there is no partial restore). A secret-free archive is also refused when this machine's own credentials are written in a form unarr cannot load, since they would be merged in: move config.toml aside, restore, then unarr login. The checksums prove integrity, not authorship: whoever holds an unencrypted archive can edit it and recompute them, so restore only archives you made — or encrypted ones, which the passphrase authenticates. A secret-free archive whose config.toml sets a credential anyway was edited after it was made, and is refused. An unencrypted archive with secrets included (what a pre-restore snapshot is, or an edited archive relabelled) is restored, but when its api_key / agent_hash are not this machine's, or it changes auth.api_url without being this machine's own identity, the dry-run and --apply warn. Without --apply nothing is written. With --apply it takes the daemon's instance lock for the whole restore — so it refuses to run while the daemon is up (unarr stop first) and a daemon cannot start halfway through — saves your current state as unarr-prerestore-<stamp>.zip in <config dir>/backups (a verbatim copy with your current secrets, 0600; it stays beside config.toml even when [backup] dir points elsewhere — --dir overrides; it is taken even when the current config.toml does not parse or is over its 4 MiB cap, so a good backup can replace a broken config, though restore will not bring that broken file back — unzip the snapshot for it; only the 128 MiB bound applies, and past it the error names the file to move aside before running the restore again), then replaces each file atomically. If a write fails, the files already replaced are put back. Because every snapshot holds secrets in the clear, each successful --apply then trims the older ones: the newest 3 and any younger than 30 days are kept, and never the one just taken. A failed restore removes nothing, and applies the same retention on demand (plain and the daemon never touch snapshots). A symlinked is updated through the link. An encrypted archive — or a secret-free one restored before — brings the archived agent id with it: restore it onto a replacement machine, not onto a second one while the original still runs, or both daemons share one identity.

Scheduled backups run inside the daemon (restart it after changing them). They are always secret-free, and a backup missed while the daemon was off is taken at its next start. An invalid table is logged at start-up and not scheduled; a failed backup is retried an hour later:

[backup]
enabled = true            # default: false
frequency = "daily"       # "daily" or "weekly"
time = "03:00"            # local time, 24h
# weekday = "sunday"      # weekly only
retention_count = 3       # scheduled backups to keep
# dir = "/srv/unarr-backups"   # default: <config dir>/backups

retention_count only ever deletes scheduled backups (unarr-scheduled-<stamp>.zip): a manual archive — say the encrypted one holding your secrets — is never pruned behind your back. unarr config check validates this table. dir must be an absolute path: a relative one would depend on the directory unarr happens to run from, so the daemon does not schedule it and unarr backup create / list / prune refuse it before touching anything (their --dir and --out flags are ordinary command-line paths, relative to where you run them). The default folder is next to the config.toml in use (so --config gets its own) rather than in the data dir, because unarr clean --all wipes the data dir on Linux and Windows. On macOS the data dir is the config dir, so unarr clean --all removes the backups too — point dir elsewhere there.

Library clean (hygiene sweep)

unarr library clean reconciles your download directory and Movies/TV library dirs, reporting — and with --apply, removing — the deterministic junk that accretes there. It never removes a valid, playable video (>= the plausibility floor, default 1 MiB), and only removes duplicates after a full byte-for-byte compare confirms they are identical (a cheap fingerprint just finds the candidates). Everything acted upon is confined to the configured download/movies/tv directories.

unarr library clean               # report only (DRY-RUN — the default)
unarr library clean --apply       # actually remove the reported orphans
unarr library clean --dry-run     # force report-only even with --apply (explicit preview)
unarr library clean --dedup-only  # only collapse byte-identical duplicate videos

Reports / removes:

• Download stubs — video files below the floor (a CDN/expired-link stub, not media).
• Orphaned partials — .part, .!qB, .aria2, .tmp, .partial with no active download.
• Duplicate videos — byte-identical copies of the same file in a directory (keeps one canonical copy, verified by fingerprint = size + first/last 1 MiB). Distinct content (a real 2160p next to a 1080p) is never touched.
• Orphaned subtitles/sidecars — .srt/.nfo/.jpg/.par2/… with no owning video. Per-track sidecars in a .unarr/ cache dir are checked against the parent release dir, so they are only removed when the release itself no longer holds the video.
• Video-less directories — empty or holding only junk/stubs.
• Media-named directories — a folder literally named movie.mkv/ (a mis-created dir).
• Suspect zero-content videos (opt-in, remove_corrupt_videos) — a video of the right size (>= floor, so not a stub) whose first and/or last 1 MiB is all zero bytes: a corrupt/zero-filled download that is unplayable yet passes the floor and dodges the dedup (its fingerprint differs from the real copy). This is a strong-but-not-absolute heuristic, so it defaults off and is removed only by this manual command with the toggle on — never by the daemon's automatic sweep. unarr library stats always counts these (shown as Suspect (zero-content)) so you can see them even without enabling removal.

Automatic cleanup (daemon)

The same sweep runs automatically after every library auto-scan in the daemon — it is the native, always-on replacement for an external cleanup script. It applies only the safe, deterministic categories, protects any partial modified in the last few minutes (a live download), logs every action, and reports the space freed. Configure it under [library.cleanup]:

[library.cleanup]
  enabled = true                   # run automatically after each auto-scan (manual command always works)
  min_video_bytes = "1MiB"         # anti-stub floor; a video smaller than this is a stub
  remove_stubs = true              # delete videos below min_video_bytes
  remove_orphan_partials = true    # delete .part/.!qB/.aria2/.tmp/.partial with no active task
  dedup_exact = true               # collapse byte-identical duplicate videos (keeps one canonical copy)
  remove_orphan_subtitles = true   # delete sidecars with no owning video (.unarr → checks parent dir)
  prune_empty_dirs = true          # remove video-less dirs and media-named dirs
  remove_corrupt_videos = false    # OPT-IN: flag/remove right-sized videos whose first/last 1 MiB is all zeros

Every category except remove_corrupt_videos defaults on (each of those is deterministic and non-destructive to valid media). remove_corrupt_videos defaults off because zero-content detection is a heuristic; enable it deliberately, and even then it is applied only by the manual unarr library clean --apply — the daemon's automatic sweep never removes a suspect video. Set enabled = false to disable the automatic post-scan sweep — the manual unarr library clean command still works regardless.

Library stats (health & composition)

unarr library stats reports the health, composition and quality of your Movies/TV library and download dir. It is a pure DRY-RUN — it only READS, never modifies anything on disk. Confined to the configured download/movies/tv directories.

unarr library stats               # readable table (dry-run — reads only)
unarr library stats --json        # emit the full stats struct as JSON (for scripts)
unarr library stats --workers 4   # limit concurrent ffprobe workers for the quality pass

Three blocks:

• Composition — number of movies, shows, seasons and episodes, plus the real on-disk space (allocated blocks, like du — not apparent size) per category (Movies vs TV Shows vs Downloads) and the average size per title.
• Health / reclaimable — the same sweep unarr library clean performs, in dry-run: stubs, orphaned partials, duplicates, orphaned sidecars, empty dirs and media-named dirs — grouped by category with the total space reclaimable. Run unarr library clean --apply to actually free it.
• Quality — resolution (2160p/1080p/720p/480p/SD), video codec (h265/h264/av1/other) and HDR breakdown, extracted with ffprobe. A file ffprobe can't read is counted as unknown and never aborts the report. Probing a large library end-to-end can take a while (bounded by --workers, default 8).

--json emits the full LibraryStats struct (composition, health, quality) for piping into scripts.

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://unarr.app"

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

[downloads]
dir = "~/Media"
# Ordered download-method preference. The web honours this list, so anything NOT
# listed is disabled — e.g. ["debrid"] means debrid-only and never falls back to
# torrent; ["debrid","usenet"] tries debrid then usenet. Omit (or use ["auto"])
# to let the server decide (default: auto — if you have debrid configured, cached
# titles use debrid automatically, otherwise torrent). Debrid/usenet must be
# configured in your TorrentClaw account — the agent only fetches links the web
# resolves. Requires unarr >= 1.1.5-beta.
preferred_methods = ["auto"]     # e.g. ["debrid"], ["debrid","usenet"], or ["auto"]
# preferred_method = "auto"      # legacy single value (still supported; superseded by preferred_methods)
max_concurrent = 3
max_download_speed = "0"         # e.g. "10MB", "500KB", "0" = unlimited
max_upload_speed = "0"
# Read-only WebDAV export of your organized library (Movies / TV Shows) so
# Infuse, Kodi, VLC, etc. can browse and play it without the web player. Opt-in,
# off by default. Only GET/HEAD/PROPFIND are served — every write verb is 405'd.
# Basic auth: username defaults to "unarr"; password defaults to a stable value
# derived from your API key (shown by `unarr status`) unless you set one. The
# mount is served on the same port as streaming, at /dav/. Requires unarr >= 1.5.0-beta.
webdav_enabled = false
# webdav_username = "unarr"
# webdav_password = ""           # blank = derive from the API key
# The mount answers only your local network (LAN, Tailscale, loopback);
# everything else gets a 404, so it stays private even when the stream port is
# reachable from the internet. Turning this on removes that restriction, and the
# Basic auth left protecting it has NO rate limiting — an exposed mount is an
# unthrottled password-guessing target. Remote playback does not use WebDAV, so
# leaving it off costs you nothing there.
# webdav_allow_wan = false

# Publish the HTTPS streaming port to your router (UPnP/NAT-PMP) so remote
# playback uses your agent's stable direct-TLS address instead of a CloudFlare
# quick tunnel, which changes hostname on every restart and gets rate-limited.
# On by default: that listener is TLS-only and every request needs a token the
# web mints, so nothing unauthenticated is reachable. The lease is renewed
# automatically and removed on shutdown. Set to false to never touch your router.
# auto_https_upnp = true

# Play Usenet (NZB) releases live from the news server instead of downloading the
# whole file first. On by default: "Play from Usenet" starts in seconds and the
# file is NOT kept in your library. A release that cannot stream (compressed or
# password-protected RAR…) falls back to a normal download automatically. Set to
# false to always download first. Configs saved by older versions carry an
# explicit `false` nobody chose; the first start after upgrading flips it to true
# once and records that in the file as `usenet_streaming_default_applied = true`
# (keep that line — it is what makes a later `false` stick). Changing it needs a
# daemon restart.
# usenet_streaming = true

[organize]
enabled = true
movies_dir = "~/Media/Movies"
tv_shows_dir = "~/Media/TV Shows"
# Folder/file layout for NEW downloads (existing files are never moved):
#   "default"  Movie (2000)/Movie (2000).mkv · Show/Season 01/Show - S01E01.mkv
#   "plex"     adds {imdb-tt…}, the show's year and episode titles — best for
#              Plex, Infuse and Emby (aliases: "infuse", "emby"), keeps
#              same-titled shows apart: One Piece (1999) {imdb-tt0388629}
#   "jellyfin" same, with [imdbid-tt…]
naming = "default"
# Optional FileBot-style templates overriding the preset. Tokens: {n} title,
# {y} year, {imdbid} {tmdbid} {tvdbid}, {collection}, {s00e00} {sxe} {s} {e}
# {s00} {e00} {e.pad(4)}, {t} episode title, {vf} 1080p. "/" = folder,
# <…> = dropped when a value inside is missing, other braces are literal.
# Preview with `unarr organize preview`; restart the daemon after changing.
# movie_format = "{n}< ({y})>< {imdb-{imdbid}}>/{n}< ({y})>< {imdb-{imdbid}}>"
# series_format = "{n}< ({y})>< {tvdb-{tvdbid}}>/Season {s00}/{n} - {s00e00}< - {t}>"

# Library-hygiene sweep — runs automatically after each auto-scan, and manually
# via `unarr library clean`. Removes only deterministic junk; a valid video
# (>= min_video_bytes) is NEVER removed. See the "Library clean" section above.
[library.cleanup]
enabled = true                   # run automatically after each auto-scan
min_video_bytes = "1MiB"         # anti-stub floor; a video below this is a stub
remove_stubs = true              # delete videos below min_video_bytes
remove_orphan_partials = true    # delete .part/.!qB/.aria2/.tmp/.partial with no active task
dedup_exact = true               # collapse byte-identical duplicate videos (keeps one canonical copy)
remove_orphan_subtitles = true   # delete sidecars with no owning video (.unarr checks the parent dir)
prune_empty_dirs = true          # remove video-less dirs and media-named dirs

[daemon]
auto_upgrade = true      # apply server-flagged upgrades in-place (since 0.9.6)
status_interval = "3s"   # how often a running download reports progress

# Log file (unarr.log in the data dir). Rotation is OPT-IN and off by default:
# read the limitations in the "Logs" section above before turning it on. With 0
# the log grows until `unarr clean` or an external logrotate trims it.
log_max_size_mb = 0      # >0 = rotate unarr.log once it reaches this many MB; 0 = never rotate
log_max_files = 3        # rotated copies to keep (unarr.log.1 … .3)
log_level = "info"       # default minimum severity for `unarr logs`: debug|info|warn|error
log_format = "text"      # `unarr logs` output: "text" (verbatim) or "json" (json-lines)

[notifications]
enabled = true

# Read by the desktop companion (tray app), not the daemon: which player the
# web's Play button opens. Empty = autodetect. See [desktop] below.
[desktop]
player = ""
# player_command = "flatpak run org.videolan.VLC --start-time={start} -- {url}"

[general]
country = "US"

Streaming reference

The in-browser player on unarr.app streams from the daemon over HLS (HTTP fragments + ffmpeg transcode for codecs the browser can't decode natively). Enabled by default — a fresh install "just works" without editing the TOML.

[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.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.hls_cache] — persistent HLS segment cache

[downloads.hls_cache]
enabled = true   # on by default
size_gb = 5      # disk budget; LRU eviction once exceeded
dir     = ""     # custom path; empty = ~/.cache/unarr/hls-cache

Key	Type	Default	Notes
enabled	bool	true	Persists finished HLS encodes per (source, quality, audio_index). A second play of the same file at the same quality reuses the segments — no ffmpeg, near-zero CPU, instant playback. Set to false to delete segments on session close (original behavior).
size_gb	int	5	Cache budget in gigabytes. When exceeded the LRU sweeper evicts the least-recently-used cached encodes hourly. Minimum 1 GB (smaller values are clamped up).
dir	string	""	Custom storage path. Empty defaults to ~/.cache/unarr/hls-cache (Linux/macOS) or the user cache dir (Windows).

What it does. First play encodes normally (ffmpeg writes segments). On session close, if every segment is on disk and ffmpeg exited cleanly, the directory is sealed with a .complete marker and kept. Next time the same source + quality combo is requested, the daemon serves segments straight from disk — no transcode, no warm-up, no CPU cost.

Why per (source, quality, audio). Renaming the file or switching quality invalidates the entry: the segments are tied to the exact source bytes and the exact ffmpeg parameters. Re-encoding generates a new key.

Eviction. A background goroutine wakes every hour. If total cache size exceeds size_gb, it deletes the oldest entries (by mtime) until under budget. Active sessions are pinned — they never get evicted mid-play.

Disable. Either edit the TOML to set enabled = false, or remove the cache directory manually (it'll be recreated as needed). Disabling does not delete existing cached segments — drop dir (or ~/.cache/unarr/hls-cache) to reclaim the space.

[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.

[downloads.funnel] — public HTTPS hostname for the daemon (CloudFlare Quick Tunnel)

[downloads.funnel]
enabled = false   # off by default

Key	Type	Default	Notes
enabled	bool	false	Spawns cloudflared tunnel --url http://localhost:<stream_port> as a child process at daemon startup. Toggle with unarr funnel on / off. Requires cloudflared on PATH.

What it does. Without a tunnel, the daemon is reachable on localhost, your LAN, and (if installed) Tailscale. That covers the same-machine and Tailscale-connected cases, but the browser-based player on unarr.app fails on any other network because HTTPS pages can't fetch HTTP resources ("mixed content"). Enabling the funnel gives the daemon a public https://<random>.trycloudflare.com hostname so the web player picks it up and playback works from anywhere — phone on cellular, friend's laptop on a foreign Wi-Fi, anywhere. The Stremio addon already works cross-network (native mpv/VLC players ignore CORS), so this is strictly a web-player fix.

Privacy posture. Bytes pass through CloudFlare's edge — TorrentClaw never relays content (we don't see your traffic), CloudFlare does. Quick Tunnels are anonymous (no CF account required); the registration is unauthenticated and the hostname is a random label, but CF logs request metadata like any CDN would. If you want zero third-party byte access, use Tailscale instead.

Limitations (free Quick Tunnels).

Aspect	Limit
Session lifetime	~6 hours, then the hostname rotates. cloudflared re-registers automatically; the web picks up the new URL on the next sync. In-flight HLS sessions break across the rotation (browser retries).
Bandwidth	No documented hard cap, but CF reserves the right to throttle. 1080p HLS (~6 Mbps) is fine; 4K HEVC at 25 Mbps may hit throttling.
Latency	+20–80 ms vs direct LAN/Tailscale (extra hop browser → CF edge → tunnel). HLS player buffer absorbs it.
Concurrency	One tunnel serves N viewers. CF rate-limits ~200 req/s, plenty for HLS segments.
TOS	CloudFlare flags Quick Tunnels as "not for production traffic". They can decommission an abusive tunnel without notice.

For heavy / high-throughput / persistent-URL use cases, switch to a CloudFlare Named Tunnel (free, needs a CF account) or run your own reverse proxy — both out of scope for the bundled command.

Disable. unarr funnel off flips enabled to false in the TOML and prompts you to restart the daemon. You can also edit config.toml directly:

[downloads.funnel]
enabled = false

Install cloudflared.

• Linux: apt install cloudflared (after adding CF's apt repo) — see https://pkg.cloudflare.com. Or pull the static binary from https://github.com/cloudflare/cloudflared/releases.
• macOS: brew install cloudflared.
• Windows: winget install --id Cloudflare.cloudflared.

If cloudflared is not on PATH the daemon logs a warning at startup and falls back to LAN/Tailscale-only reachability.

[desktop] — which player Play opens

Read by the unarr desktop companion (the tray app that registers the unarr:// handler), not by the daemon. Pressing Play on the web sends an unarr://play link to it, and this section decides what opens.

[desktop]
# Empty = autodetect. Or: "mpv", "vlc", "iina" (macOS), "mpc" (Windows),
# "system" (whatever your OS opens video with).
player = ""

# An explicit command line, for players none of those names reach.
# Wins over `player`. See below.
# player_command = "flatpak run org.videolan.VLC --start-time={start} -- {url}"

Key	Type	Default	Notes
player	string	""	"" = autodetect. "mpv" also resolves Celluloid (it embeds mpv and installs no mpv binary). "system" uses your OS default video app. A player that isn't installed falls back to autodetect and notifies you — the setting is never silently ignored. Watching in the browser is not a value here: that's the web's own "Web player" button.
player_command	string	""	Explicit command line with placeholders (below). Outranks player; while it is set, the tray's Player submenu is shown disabled.

How the player is chosen, most specific first:

1. player_command — your own command line
2. player — a name from the table above
3. autodetect — mpv/Celluloid → VLC → IINA (macOS) / MPC-HC (Windows)
4. your OS default video application
5. the browser, as a last resort, so a click always plays something

Step 5 is a fallback, not a choice: if you want to watch in the browser, the web has its own "Web player" button, and going through the desktop app to get there would be a second route to the same place. Steps 1 and 4 exist because a Flatpak/Snap/AppImage install exposes no binary on PATH, and mpv.net or SMPlayer are their own spellings. Step 4 asks the system directly (freedesktop MIME association on Linux, LaunchServices on macOS, the registered file association on Windows), so it finds those — but it can only pass a URL, so playback starts from the beginning. Steps 2 and 3 know the player's flags and can pass resume position, title and language preferences.

player_command placeholders. The template is split into arguments here and executed directly — never through a shell — so quoting is the only shell syntax that applies. An argument whose placeholder has no value for a given stream is dropped whole, so --start={start} simply disappears when there is nothing to resume.

Placeholder	Value
{url}	The stream URL. Appended automatically if the template never mentions it.
{web}	The unarr web player page for this stream (falls back to {url}).
{start}	Resume position in seconds. Absent when starting from the beginning.
{title}	Display title for the player window/OSD.
{alang} / {slang}	Preferred audio / subtitle languages, comma-separated.
{subfile}	URL of an external subtitle file to side-load. First one only — see the note below.

{subfile} carries a single subtitle. unarr can side-load several external subtitle files (AI translations and shared provider subtitles), but a placeholder always substitutes inside ONE argument, so a template cannot emit a repeatable flag more than once. {subfile} therefore expands to the first subtitle only, and the argument disappears when there is none. The built-in players (mpv, Celluloid, VLC) receive all of them — use one of those if you want the full subtitle menu.

# Flatpak VLC (no `vlc` on PATH)
player_command = "flatpak run org.videolan.VLC --start-time={start} -- {url}"

# mpv.net on Windows
player_command = 'C:\Program Files\mpv.net\mpvnet.exe --start={start} --force-media-title={title} -- {url}'

# SMPlayer (its own flag spellings)
player_command = "smplayer -media-title {title} -start {start} {url}"

Environment variables

Environment variables override config file values:

export UNARR_API_KEY=tc_your_api_key
export UNARR_API_URL=https://unarr.app
export UNARR_COUNTRY=ES
export UNARR_DOWNLOAD_DIR=~/Media

# Desktop companion — one-off override without editing the TOML
export UNARR_DESKTOP_PLAYER=vlc
export UNARR_DESKTOP_PLAYER_COMMAND="flatpak run org.videolan.VLC -- {url}"

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)

Telemetry

The agent reports a small set of lifecycle events to the server — enough to see why an agent that connected never came back:

• Onboarding: login succeeded, first sync completed, or a start-up failure (missing config, a stream port already in use, a permission error).
• Exit: whether the daemon was stopped by you, crashed, or exited normally.

No file names, library contents, search terms, or download activity are sent — only these lifecycle signals plus the agent's version and OS. It helps us fix the setup problems that make agents fail on the first run.

To turn it off completely:

[telemetry]
enabled = false

or with an environment variable (wins over the config file — handy for headless/Docker):

UNARR_TELEMETRY=off unarr start

When disabled the agent sends nothing — it still registers, syncs, and downloads exactly the same. Telemetry is purely additive.

Remote library as a local folder (optional)

unarr mount exposes completed Real-Debrid / AllDebrid / TorBox / Torrin files and compatible NZBs as a local folder, reading media on demand. This is disabled by default and independent of the existing WebDAV export of downloaded files. Enable the mount with unarr mount and connect providers on the Unarr website. unarr prepares rclone automatically, explains missing filesystem drivers before asking permission to install them, and creates a default mount folder. The normal agent service owns the mount after the command exits and retries it after transient failure or login/reboot. Run unarr init first to configure the normal agent. The command confirms saved settings and an activation request; check the folder and agent logs to verify it is mounted. Use unarr umount to disable it, unarr config mount for advanced local settings, or unarr mount <directory> to choose a destination. On the website, Add to local Usenet folder sends only the selected NZB to the agent's managed inbox; manual NZB copies remain supported.

Persistent mount/umount use the single default agent configuration; custom --config and shell-only overrides are refused before login or service changes. Use unarr mount serve --config /path/to/config.toml for a separately managed WebDAV process. Disabling the mount leaves an intentionally stopped agent stopped.

See setup, configuration and limitations and the performance report.

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).

Scan

Walk a folder recursively, analyze each video file with ffprobe, and sync quality data to your account.

unarr scan ~/Media              # scan default download dir
unarr scan /mnt/nas/Movies      # scan a specific path
unarr scan ~/Media --status     # show last scan results without re-scanning
unarr scan ~/Media --workers 4  # use 4 parallel ffprobe workers
unarr scan ~/Media --no-sync    # analyze locally without uploading results

The daemon also runs an automatic background scan when it detects new files in the download directory.

Mirrors

Mirrors are alternate base URLs the agent falls back to when the primary domain is unreachable — useful for bypassing DNS blocks, ISP filters, or short-lived outages without restarting the agent.

unarr mirrors list     # show currently configured mirrors
unarr mirrors update   # refresh from the server's canonical list
unarr mirrors test     # probe every configured mirror for latency and reachability

Coming Soon

These commands are planned for future releases:

Command	Description
unarr moreseed	Find same quality with more seeders
unarr compare	Compare two torrents side by side
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.