Skip to content

Getting started

This guide covers installing upPollo, creating your first configuration, keeping the binary up to date, and enabling shell completion.

Requirements

MediaInfo and ffmpeg must be available in your system PATH.

Some seedbox providers (e.g. Ultra.cc) ship limited ffmpeg builds without HDR tonemapping support. If your HDR screenshots look too dark, washed out, or oversaturated, configure a custom ffmpeg build — see Custom FFmpeg.

Screenshots from Dolby Vision Profile 5 releases need ffmpeg with the libplacebo filter and a Vulkan device, otherwise they get a green/purple color cast. The same guide covers the setup per platform.

Installation

Pre-built binaries

Download the latest release for your platform from the Releases page. On Linux and macOS, make the binary executable:

chmod +x ./upPollo

go install

Requires Go 1.27 or newer. Install a specific stable version (recommended):

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

@latest also works but may resolve to a pre-release (-beta, -rc, nightly) during development cycles. See Releases for available versions.

Docker

upPollo is also available as a Docker image — see Docker.

First configuration

On first run, upPollo generates a default config at ~/.config/upPollo/config.yaml. You can also generate one explicitly, optionally at a custom location:

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

Edit the file and fill in the options below. Everything else can keep its default for a first upload.

Option What it is for Where to get it
trackers.rhd / trackers.aw: api_key, announce_url Dupe check and upload API key from your tracker profile, announce URL from the tracker's upload page
torrent_client plus the matching section Seeding the new torrent Your client's WebUI/RPC connection, see Configuration: Torrent clients
tmdb_api_key Identifying every release TMDb API key
tvdb_api_key TVDb ID and air dates for series TVDb API key
mal_client_id MyAnimeList ID lookup for AnimeWorld uploads MyAnimeList client ID
screenshots.services Screenshots in the upload description Screenshot hosts

A filled-in example for the API keys and screenshots:

tmdb_api_key: "<your TMDb v3 API key>"
tvdb_api_key: "<your TVDb v4 API key>"
mal_client_id: "<your MyAnimeList client ID>" # only for AnimeWorld

screenshots:
    num: 4
    services:
        - name: "ptscreens"
          api_key: "<your ptscreens API key>"
          enabled: true
          order: 1
        - name: "imgbox"   # no key needed, used when ptscreens fails
          enabled: true
          order: 2

TMDb API key

upPollo resolves every release through TMDb: title search, German and English titles, the IMDb and TVDb IDs, and episode data for the release date filter. Without a key, identification fails and nothing is uploaded, for movies and series alike.

  1. Create a free account on themoviedb.org.
  2. Request an API key under Settings → API.
  3. Copy the value labelled API Key into tmdb_api_key.

upPollo calls the v3 API with this key. The longer API Read Access Token on the same page does not work.

TVDb API key

Movies don't need it. For series, upPollo uses the TVDb v4 API to:

  • look up the TVDb ID when TMDb has none; the ID is sent to the tracker with the upload,
  • read the episode air dates that the release date filter uses to skip bulk releases and seasons whose finale aired outside the grace period, see Upload filters.

Without a key, series uploads still go through, but upPollo reports TVDb errors. The release date filter then no longer skips episode releases of series for which TMDb lists a TVDb ID, which covers most series.

Get a key from TVDb and put it into tvdb_api_key. upPollo logs in with the key alone and sends no subscriber PIN, so a key that requires a PIN is rejected at login.

MyAnimeList client ID

Only needed for AnimeWorld. AnimeWorld uploads include a MyAnimeList ID. If you don't pass one with --mal, upPollo searches MyAnimeList and lists up to ten results with their English title, start year and type. Seasons are separate entries on MyAnimeList, so check that you pick the right one. Entries matching the release type (series or movie) are listed first. The search runs after the filters and the dupe check, so it only comes up for releases that are going to be uploaded. Dry runs skip it.

At the prompt you can pick a result, enter a MAL ID or paste a MyAnimeList URL. upPollo looks up entered IDs and asks again if MyAnimeList doesn't know them. Pressing Enter skips the prompt, and the upload goes out with MAL ID 0.

upPollo searches with the English TMDb title first, then the title from the release name, and the German title last, because MyAnimeList lists hardly any German titles. The search goes through the official MyAnimeList API, which requires a client ID:

  1. Sign in on myanimelist.net and open Account Settings → API, then select Create ID.
  2. Set App Type to other. MyAnimeList then issues a client ID without a client secret; upPollo doesn't need a secret.
  3. Fill in the required fields. upPollo doesn't log in to MyAnimeList, so it never uses the redirect URL; http://localhost is enough.
  4. Copy the Client ID into mal_client_id.

Without a client ID, upPollo skips the search and asks for the MAL ID directly. In unattended mode there is no prompt and no search, so pass --mal there.

Screenshot hosts

upPollo takes num screenshots per upload and links them in the description. Enable at least one host under screenshots.services. Each image goes to the enabled host with the lowest order first. If that upload fails, or the image is larger than the host accepts, upPollo tries the next host. The images are uploaded one after another unless screenshots.parallel_uploads is raised, see Configuration: Screenshots.

Service API key Max. image size Where to get the key
ptscreens required 100 MB Your ptscreens account settings, section API
imgbb required 32 MB api.imgbb.com, sign in and select "Get API key"
imgbox not needed 10 MB —

An enabled ptscreens or imgbb entry with an empty api_key makes the config invalid, and upPollo stops with an error when it loads the config. With no host enabled, upPollo warns No Screenshot Service Enabled! and uploads without screenshots.

Check the config

upPollo config validate

This loads the config, reports invalid values, and tests the connection to your torrent client and to enabled Radarr, Sonarr, and cross-seed instances. It does not test the TMDb, TVDb, or screenshot host keys. A dry run on a real release uses the TMDb key (and for a series the TVDb key) during identification and the tracker API key during the dupe check, so a wrong key shows up there as an error or warning. Nothing is uploaded:

upPollo upload --dry-run "/path/to/release"

A wrong screenshot host key only shows up during the first real upload, as a failed screenshot upload. On RocketHD the torrent can be on the tracker by then, and upPollo warns that it has no screenshots.

See Configuration for all options, config file search order, and how config migration keeps your file up to date across versions.

First upload

upPollo upload "/path/to/Movie.2024.German.DL.1080p.WEB.h264-GROUP"

upPollo identifies the release, asks for confirmation where needed, generates MediaInfo, creates the torrent, uploads it, and adds it to your torrent client. On RocketHD the screenshots are added to the description after the upload, on AnimeWorld they are taken before it (see Configuration: Screenshots). To see what would happen without uploading, use --dry-run. See the CLI reference for all flags.

Updating

Update to the latest release with the built-in updater:

upPollo update

This checks Codeberg for the latest release, downloads the correct binary for your platform, and replaces the current one (on Windows, you are prompted to replace it manually). If upPollo is installed in a protected location you may need elevated permissions (e.g. sudo).

Automatic updates

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

channel takes stable or pre. latest and nightly are accepted as aliases for them, matching the Docker tag names. Any other value is rejected when the config is loaded.

  • In CLI mode, updates are checked and applied before each command.
  • In API mode, updates are checked at the scheduled time and applied after all active uploads and queued CrowdNFO submissions complete.
  • In Docker, auto-update is disabled automatically — pull a new image instead, see Docker: Updating.

Shell completion

upPollo provides completion for all subcommands and flags. The binary must be in your PATH.

Bash (~/.bashrc):

source <(upPollo completion bash)

Zsh (~/.zshrc):

source <(upPollo completion zsh)

Fish:

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

Run upPollo completion --help for more options.