CLI.md

PakFu CLI Reference

PakFu's CLI exposes the same archive and conversion core used by the desktop app. Use it for scripted extraction, package validation, reproducibility manifests, asset conversion, extension diagnostics, and update checks.

Usage

pakfu[.exe] --cli [options] [archive-or-folder]

archive-or-folder can point to a supported package file or to a directory tree.

Core Actions

Option	Purpose
-l, --list	List archive entries.
-i, --info	Show archive summary information.
-x, --extract	Extract selected entries or the whole archive.
--save-as <archive>	Rebuild selected entries into a new archive.
--validate	Validate path safety, duplicates, readability, dependency hints, and known material/PROC relationships.
--compare <archive-or-folder>	Compare selected content against another package or folder. Returns 1 when content differs.
`--asset-graph <text	json
`--package-manifest <text	json>`
--convert <format>	Convert selected assets through the shared conversion backend.
--preview-export <entry>	Export the preview rendition of one archive entry.
--check-updates	Query GitHub Releases for updates.

Selection And Mounting

Option	Purpose
--entry <path>	Limit actions to an exact archive entry. Repeat for multiple entries.
--prefix <dir>	Limit actions to entries under a directory prefix. Repeat for multiple prefixes.
--mount <entry>	Mount a nested archive entry before running the requested action.
-o, --output <dir>	Write command output to a directory or file, depending on the action.

Save-As Options

Option	Purpose
`--format <pak	sin
--quakelive-encrypt-pk3	Write ZIP-family --save-as output with Quake Live Beta PK3 encryption.

Conversion Options

Option	Purpose
--convert-kind <kind>	Conversion category: image, sound, video, map, archive, model, text, other, or auto.
--palette-source <mode>	Source palette for indexed image inputs: adaptive, quake1, quake2, embedded, or game.
--palette-target <mode>	Target palette for indexed image outputs: adaptive, quake1, quake2, embedded, or game.
`--dither <on	off>`
--alpha-threshold <0..255>	Alpha cutoff for transparent palette index mapping.
`--mip-level <n	all>`
--bsp-decompile-mode <mode>	BSP export mode: best, geomonly, entities, or hull.
`--video-frames <png	jpg>`
--frame-step <n>	Export every nth video frame.
--export-audio	Export cinematic audio when present.

Image outputs include png, jpg, jpeg, bmp, gif, tga, tif, tiff, pcx, wal, swl, mip, lmp, ftx, and dds. Sound, map, and video targets include wav, map, txt, and frame export formats.

Extension Commands

Option	Purpose
--list-plugins	List discovered extension commands.
--plugin-report	Print extension search roots, trust scope, manifest warnings, and capability notes.
--run-plugin <plugin[:command]>	Run one extension command against the loaded archive.
--plugin-dir <dir>	Add an extension search directory. Repeat for multiple directories.

Installation Profile Actions

Option	Purpose
--list-game-installs	List configured installations.
--auto-detect-game-installs	Auto-detect supported game installations and save profile changes.
--select-game-install <selector>	Select an installation by UID, game key, or display name.

Legacy aliases remain accepted:

• --list-game-sets
• --auto-detect-game-sets
• --select-game-set <selector>

Diagnostics

Option	Purpose
--platform-report	Print platform paths, Qt/runtime metadata, extension state, installation profiles, and shell-integration expectations.
--qa-practical	Run practical archive-ops smoke QA. This option must be used by itself.
--update-repo <owner/name>	Override the update-check repository.
`--update-channel <stable	beta

Examples

pakfu --cli --info path/to/archive.pk3
pakfu --cli --list path/to/archive.wad
pakfu --cli --extract -o out_dir path/to/archive.resources
pakfu --cli --extract --prefix maps -o maps_out path/to/archive.pk3
pakfu --cli --validate path/to/archive.pk4
pakfu --cli --compare rebuilt.pk3 path/to/source.pk3
pakfu --cli --asset-graph json -o graph.json path/to/archive.pk4
pakfu --cli --package-manifest json -o manifest.json path/to/archive.pk3
pakfu --cli --save-as mod_subset.pk3 --format pk3 --prefix textures path/to/archive.pk3
pakfu --cli --convert png --prefix textures -o converted_textures path/to/archive.pk3
pakfu --cli --preview-export gfx/conback.lmp -o previews path/to/pak0.pak
pakfu --cli --mount nested/maps.pk3 --list path/to/archive.pk3
pakfu --cli --list-plugins
pakfu --cli --plugin-report --plugin-dir examples/extensions/metadata-dump
pakfu --cli --run-plugin example:inspect-cfg --entry scripts/autoexec.cfg path/to/archive.pk3
pakfu --cli --platform-report
pakfu --cli --check-updates
pakfu --cli --qa-practical
pakfu --cli --list-game-installs
pakfu --cli --auto-detect-game-installs
pakfu --cli --select-game-install quake2

Exit Codes

Code	Meaning
0	Command succeeded.
1	Compare command completed and found differences.
2	Command-line error, load failure, validation failure, extraction failure, update-check failure, or another runtime error.