Usage

Query — generate .refs files by category

fhtoolkit query [-c CATEGORY ...] [--all] [--dump-categories]
                 [--arch ARCH] [--branch BRANCH] [--out OUT] [--merge-to MERGE_TO]

Flag	Meaning
-c / --category	Repeatable — pick specific categories (default: x86_64 arch, stable branch)
--all	Generate refs for every category
--dump-categories	List available categories without generating anything
--arch	Flatpak architecture (default x86_64)
--branch	Flatpak branch (default stable)
--out	Output directory for *.refs files (default refs)
--merge-to	Merge all selected category refs into a single combined file

Example — list categories, then generate refs for two of them into a merged file:

fhtoolkit query --dump-categories
fhtoolkit query -c Development -c Utility --merge-to refs/dev-and-utility.refs

Download — fetch .flatpakref descriptors

fhtoolkit download [--refs-file FILE ...] [--refs-dir DIR] [--out OUT]
                    [--skip-existing / --no-skip-existing] [--throttle SECONDS]
                    [--limit N] [--timeout SECONDS]

Flag	Meaning
--refs-file / -f	Repeatable — one or more specific .refs files
--refs-dir	A directory of .refs files instead of naming them individually
--out	Output directory for descriptors (default flatpakrefs)
--skip-existing	Default true — don't re-download descriptors already present
--no-skip-existing	Force re-download
--throttle	Delay between downloads, in seconds
--limit	Cap the number of descriptors downloaded (0 = unlimited)
--timeout	Per-request timeout, in seconds (default 30)

Example:

fhtoolkit download --refs-dir refs/ --out flatpakrefs/ --throttle 0.5

Legacy standalone scripts

Query.py and Download.py at the repo root are preserved wrappers around the same underlying logic, kept for backward compatibility. The packaged fhtoolkit CLI is the preferred entry point going forward — the standalone scripts should be treated as compatibility shims, not the primary interface.