feat: initial commit — unarr CLI

Search, inspect, stream, and download torrents from the terminal. Replaces the entire *arr stack with a single binary.
2026-03-28 11:29:42 +01:00 · 2026-03-28 11:29:42 +01:00 · 29cf0a0126
commit 29cf0a0126
85 changed files with 10178 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,216 @@
+# unarr
+
+[![CI](https://github.com/torrentclaw/torrentclaw-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/torrentclaw/torrentclaw-cli/actions/workflows/ci.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/torrentclaw/torrentclaw-cli)](https://goreportcard.com/report/github.com/torrentclaw/torrentclaw-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Go Version](https://img.shields.io/github/go-mod/go-version/torrentclaw/torrentclaw-cli)](go.mod)
+
+Powerful terminal tool for torrent search and management.
+
+Search 30+ torrent sources, inspect torrent quality, discover popular content, find streaming providers, and manage your media collection — all from your terminal.
+
+<!-- GIF demo placeholder -->
+<!-- ![unarr Demo](docs/demo.gif) -->
+
+## Installation
+
+### Go install
+
+```bash
+go install github.com/torrentclaw/torrentclaw-cli/cmd/unarr@latest
+```
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew install torrentclaw/tap/unarr
+```
+
+### GitHub Releases
+
+Download prebuilt binaries for Linux, macOS, and Windows from [GitHub Releases](https://github.com/torrentclaw/torrentclaw-cli/releases).
+
+### Build from source
+
+```bash
+git clone https://github.com/torrentclaw/torrentclaw-cli.git
+cd torrentclaw-cli
+make build
+```
+
+## Quick Start
+
+```bash
+# Configure (first time)
+unarr config
+
+# Search for content
+unarr search "breaking bad" --type show --quality 1080p
+
+# Inspect a torrent
+unarr inspect "magnet:?xt=urn:btih:ABC123&dn=Movie.2023.1080p.BluRay.x265"
+
+# Popular content
+unarr popular --limit 20
+
+# Recently added
+unarr recent
+
+# Where to watch (streaming + torrents)
+unarr watch "oppenheimer" --country ES
+
+# System statistics
+unarr stats
+```
+
+## Commands
+
+### Search
+
+Search the unarr catalog with advanced filters.
+
+```bash
+unarr search "inception" --sort seeders --min-rating 7 --lang es
+```
+
+**Filters:**
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--type` | Content type | `movie`, `show` |
+| `--quality` | Video quality | `480p`, `720p`, `1080p`, `2160p` |
+| `--lang` | Audio language (ISO 639) | `es`, `en`, `fr` |
+| `--genre` | Genre filter | `Action`, `Comedy`, `Drama` |
+| `--year-min` | Minimum release year | `2020` |
+| `--year-max` | Maximum release year | `2026` |
+| `--min-rating` | Minimum IMDb/TMDb rating | `7` |
+| `--sort` | Sort order | `relevance`, `seeders`, `year`, `rating`, `added` |
+| `--limit` | Results per page (1-50) | `10` |
+| `--page` | Page number | `2` |
+| `--country` | Country for streaming info | `US`, `ES` |
+
+### Inspect
+
+TrueSpec analysis — parse a torrent and show detailed specs.
+
+```bash
+unarr inspect "Oppenheimer.2023.1080p.BluRay.x265"
+```
+
+Accepts magnet URIs, 40-character info hashes, or torrent names.
+
+Output includes: quality, codec, size, seeds, languages, source, quality score, and health.
+
+### Watch
+
+Find where to watch — streaming services alongside torrent options.
+
+```bash
+unarr watch "oppenheimer" --country ES
+```
+
+Shows legal streaming options first (subscription, free, rent, buy), then torrent alternatives.
+
+### Popular
+
+Show trending content ranked by community engagement.
+
+```bash
+unarr popular --limit 20
+```
+
+### Recent
+
+Show the most recently added content.
+
+```bash
+unarr recent --limit 20
+```
+
+### Stats
+
+Display unarr system statistics.
+
+```bash
+unarr stats
+```
+
+### Config
+
+Interactive configuration setup.
+
+```bash
+unarr config
+```
+
+Saves to `~/.config/unarr/config.yaml`.
+
+## Alias
+
+You can use `un` as a shorthand for `unarr`:
+
+```bash
+un search "breaking bad" --type show
+un popular --limit 5
+```
+
+## 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 commands support `--json` for scripting:
+
+```bash
+# 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.yaml`
+
+```yaml
+api_url: https://torrentclaw.com
+api_key: tc_your_api_key_here
+country: US
+```
+
+Environment variables (override config file):
+
+```bash
+export UNARR_API_URL=https://torrentclaw.com
+export UNARR_API_KEY=tc_your_api_key
+export UNARR_COUNTRY=ES
+```
+
+## Coming Soon
+
+These commands are stubbed and will be available in future releases:
+
+- `unarrupgrade` — Find a better version of a torrent
+- `unarrmoreseed` — Find same quality with more seeders
+- `unarrcompare` — Compare two torrents side by side
+- `unarrscan` — Scan your media library for upgrades
+- `unarradd` — Search and add torrents to your client
+- `unarrmonitor` — Watch for new episodes of a series
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and guidelines.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.