upPollo

README

upPollo

upPollo is a cross-platform CLI utility designed to streamline uploads to RocketHD (RHD). It automates metadata extraction, naming, dupe checking, torrent creation, release identification via IMDb, TMDb and TVDb and integration with torrent clients.

---

Features

• Generate and parse MediaInfo.
• Generate names as per RHD rules.
• Automatically obtain TMDb/IMDb/TVDb identifiers via XREL, SRRDB or CrowdNFO.
• Check for potential dupes.
• Generate torrent files (mkbrr comes bundled with upPollo).
• Generate and upload screenshots (ptscreens, imgbox, imgbb).
• Automatically hardlink or copy files to download folder if needed.
• Upload to RocketHD.
• Integrate with qBittorrent (fast resume, instant seeding).
• Automatically upload metadata to CrowdNFO.
• Compatible with UNIT3Ds latest info_hash changes.

Docker Support

upPollo is available as a Docker image for easy deployment and management. Run upPollo in a containerized environment with support for both CLI and API modes. Docker deployment simplifies configuration management, ensures consistent environments across different systems, and makes it easy to integrate with other containerized services like qBittorrent, Radarr, and Sonarr.

For complete setup instructions, volume configuration, networking, and troubleshooting, see the Docker documentation.

Media Library Integration (Radarr/Sonarr)

upPollo can upload directly from your media library by querying Radarr or Sonarr to find the original release names. This is useful when your media files have been renamed by Radarr/Sonarr. upPollo automatically detects media library paths, queries the APIs for original release names, and creates proper release structures with hardlinks.

For detailed setup instructions, configuration options, path mapping, and troubleshooting, see the Media Library Integration documentation.

API Mode (Limited Access)

Important: This feature is currently restricted to certain user groups.

upPollo can run as an HTTP API server, enabling programmatic uploads via REST endpoints. This is perfect for automation with qBittorrent webhooks, cross-seed integration, or custom scripts. API mode features queue-based processing, automatic logging, and optional cross-seed integration to trigger searches before uploads begin.

For complete setup instructions, endpoint documentation, usage examples, and cross-seed integration, see the API Mode documentation.

---

Next Up

• Support for other torrent clients.
• Full disk support.

---

Far in the future

• Support for other trackers. (collaborators welcome)

---

Installation

Requirements

You must have MediaInfo and ffmpeg available in your system PATH for upPollo to work correctly.

Note for Seedbox Users: Some seedbox providers (e.g., Ultra.cc) have limited FFmpeg builds that lack HDR tonemapping support. If your HDR screenshots appear too dark, washed out, or oversaturated, you can configure a custom FFmpeg installation. See the Custom FFmpeg Configuration Guide for detailed instructions.

Pre-built Binaries

Download the latest release for your platform from the Releases page.

Note: On Unix-based operating systems (Linux, macOS), you may need to make the downloaded binary executable by running:

chmod +x ./upPollo

Installation via GO

Disclaimer: upPollo requires Go version 1.25 or newer to be installed this way. Please ensure you have Go 1.25+ installed before running go install. If your Go version is older, installation may fail due to incompatibilities.

upPollo can be installed using go install, we recommend installing a specific stable version:

go install codeberg.org/upPollo/upPollo@v1.9.1

See Releases for available versions.

Alternatively, you can install the latest version (which may include pre-release versions during development cycles):

go install codeberg.org/upPollo/upPollo@latest

Note: @latest may include pre-release versions during development cycles. Pre-release versions are marked with suffixes like -beta, -rc, etc. For production use, we recommend installing a specific stable version as shown above.

Updating upPollo

You can update upPollo to the latest version using the built-in update command:

./upPollo update

This command will:

• Check for the latest release on Codeberg.
• Download the correct binary or archive for your platform.
• Extract and replace the current binary automatically (on Windows, you'll be prompted to replace the binary manually).

Note: You may need to run the update command with elevated permissions (e.g., sudo) if upPollo is installed in a protected location.

Automatic Updates

Configure automatic updates in your config.yaml:

auto_update:
    enabled: true
    channel: "stable"  # or "pre" for nightly builds
    schedule: "02:00"  # API mode only: time to check (local system time)

• CLI Mode: Updates are checked and applied before each command execution.
• API Mode: Updates are checked at the scheduled time and applied after all active uploads complete.

Note for Docker Users: Auto-update is automatically disabled when running in Docker containers. To update in Docker, pull the latest image instead. See the Docker documentation for details.

Shell Completion

upPollo supports auto-completion for all subcommands and flags. To enable it, add the appropriate line to your shell configuration:

Bash (~/.bashrc):

source <(upPollo completion bash)

Zsh (~/.zshrc):

source <(upPollo completion zsh)

Fish (~/.config/fish/completions/upPollo.fish):

upPollo completion fish > ~/.config/fish/completions/upPollo.fish

Note: Make sure the upPollo binary is in your PATH for completion to work. Run upPollo completion --help for more options.

---

Usage

• See ./upPollo --help for all available commands and options.

./upPollo upload [file path] [flags]

Checking Before Upload

Validate a release without uploading by running release identification, filter checks, and dupe checks. The command exits with code 0 if the upload would succeed, or 2 if blocked by filters or dupes and 1 on any other error.

./upPollo upload check [file path] [flags]

Supports the same identification flags as upload (--imdb, --tmdb, --unattended, --skip-name-enrichment) plus --json for JSON output.

CLI Parameters & Flags

Positional Arguments:

• [file path] Path to the media file or directory you want to upload.

Flags:

• -u, --unattended Enable unattended upload (skips confirmation prompts; use at your own risk).

• -f, --ignore-filters Disable filters for this upload (i.e. if you want to upload an english release for a request).

• -d, --ignore-dupe Skip the dupe check for this upload (useful for false positive dupe detection).

• --imdb <id> Pass an IMDb ID (e.g., tt1234567) for easier identification of the release.

  Note: If you provide an IMDb ID using this flag, upPollo will skip searching for NFO files and querying external APIs (such as XREL, SRRDB, CrowdNFO) to identify the release. The provided IMDb ID will be used directly for metadata enrichment and identification.

• --tmdb <id> Pass a TMDb ID (e.g., 1234567) for easier identification of the release.

  Note: If you provide a TMDb ID using this flag, upPollo will skip searching for NFO files and querying external APIs (such as XREL, SRRDB, CrowdNFO) to identify the release. The provided TMDb ID will be used directly for metadata enrichment and identification.

• -a, --anon Enable anonymous upload.

• -p, --personal-release Enable upload as personal release.

• -i, --internal Mark upload as internal release.

• --check-hash Enable hash checking for the torrent before seeding. This flag overrides the qbittorrent.hash_check config setting.

• --qbit-category <category> Set the category for the torrent in qBittorrent.

• --qbit-tags <tag> Set tags in the torrent client (can be specified multiple times for multiple tags).

• --qbit-auto-tmm Enables automatic torrent management in qBittorrent.

• -n, --skip-name-enrichment Skip release name enrichment. Only set this if you are sure the release name matches the tracker rules.

Example:

./upPollo upload "/path/to/mediafile.mkv" --unattended --anon --imdb tt1234567 --check-hash --qbit-category "Movies" --qbit-tags "Action" --qbit-tags "2024"

---

Configuration

upPollo requires a config.yaml file to define your environment, API keys, and qBittorrent connection settings.

First-Time Setup

When you run upPollo for the first time, it will automatically generate a default configuration file at ~/.config/upPollo/config.yaml. You can also manually generate a config file using:

./upPollo config generate

To generate a config file at a custom location:

./upPollo config generate /path/to/custom/config.yaml

After generation, edit the config file to add your API keys and settings.

Managing Your Configuration

Validating Configuration

You can validate your configuration file and test connectivity to all configured services:

./upPollo config validate

This command will:

• Verify YAML syntax and required fields
• Test connectivity to qBittorrent, Radarr instances, Sonarr instances, and Cross-Seed (if configured)
• Display a summary of your configuration

To validate a specific config file:

./upPollo config validate -c /path/to/custom/config.yaml

Migrating Configuration

upPollo can manually migrate your configuration file to the latest version:

./upPollo config migrate

This will add any new configuration options from the latest template while preserving all your existing settings. A backup is created automatically before migration.

To migrate a specific config file:

./upPollo config migrate /path/to/custom/config.yaml

To force a migration even when no new options are detected (useful for reformatting or troubleshooting):

./upPollo config migrate --force

or using the short flag:

./upPollo config migrate -f

Configuration File Location

upPollo searches for config.yaml in the following locations (in order of priority):

1. Custom path specified via the --config or -c flag (highest priority)
2. Current working directory (. or ./configs)
3. Executable directory (same directory as the upPollo binary or its configs/ subdirectory)
4. User config directory (~/.config/upPollo/config.yaml)

Using a Custom Config File

You can specify a custom configuration file location using the --config or -c flag:

./upPollo --config /path/to/custom/config.yaml upload /path/to/mediafile.mkv

or the short form:

./upPollo -c /path/to/custom/config.yaml upload /path/to/mediafile.mkv

Config Migration

upPollo features an automatic config migration system that adds new configuration options when they're introduced in new versions. This ensures your config stays current without manual updates while preserving all your custom settings.

Key features:

• Automatically adds new config options with their defaults
• Preserves all your existing values
• Works with deeply nested configurations
• Creates automatic backups before migration

For complete details and examples, see the Config Migration documentation.

Example Configuration

See the example configuration file at configs/config.example.yaml for all available options.

---

Development

Run Tests

go test ./...

Build All Platforms (via CI)

On every tagged commit, the CI/CD pipeline builds and publishes binaries for:

• Linux (amd64)
• macOS (amd64 & arm64)
• Windows (amd64)

---

Contributing

We welcome contributions! Please read our CONTRIBUTING.md for guidelines before opening issues or pull requests.

---

License

MIT

---

Acknowledgements

• Go
• mkbrr
• qBittorrent
• TMDb / IMDb