Skip to main content

FH-RefToolkit Overview

FH-RefToolkit generates Flatpak .refs lists from Flathub's AppStream metadata and downloads the corresponding .flatpakref descriptor files. It's the toolkit that turns "I want a curated list of Flatpak apps by category" into concrete, downloadable descriptor files that a deployment or archive pipeline can use.

Who it's for​

An operator building deployment lists or archiving Flatpak app descriptors — for example, feeding a curated app catalog into a Linux distribution image or an offline software archive.

The core concept​

Two subcommands under one packaged CLI (fhtoolkit), plus preserved legacy standalone scripts (Query.py, Download.py) for backward compatibility:

fhtoolkit query    <-- fetch Flathub AppStream XML, stream-parse components,
                       write one-line-per-ref .refs files, grouped by category
fhtoolkit download <-- read .refs files, fetch the matching .flatpakref
                       descriptor for each app ID over HTTPS

Query fetches AppStream XML for a given architecture, parses it as a stream (not loaded fully into memory), normalizes categories, and writes one .refs file per category — with an optional --merge-to to combine several categories into one file, and --dump-categories to just list what categories exist without generating anything.

Download reads one or more .refs files (or an entire directory of them), collects the Flatpak app IDs, and fetches each one's .flatpakref descriptor from dl.flathub.org, skipping files that already exist by default.

Why this shape​

Query and download are separated deliberately: generating the ref list is fast and doesn't touch the network much, while downloading descriptors is the slow, network-bound step. Keeping them as separate subcommands (rather than one combined command) lets an operator regenerate and inspect a ref list before committing to the download pass — and re-run just the download step with --skip-existing if it's interrupted partway through.