CLI overview

zpack <command> [args]

  pack     <input-dir> <output.zpak>
  list     <archive.zpak>
  unpack   <archive.zpak> <output-dir>
  verify   <archive.zpak>
  ids      <archive.zpak>
  manifest <archive.zpak>

  -h, --help       Print this message
  -V, --version    Print the version

Arguments are positional and every command takes a fixed number of them. There are no flags beyond --help and --version.

Commands

Command	Reads	Writes	Page
pack	A directory tree	A new .zpak	pack
list	The index only	stdout	list
unpack	The whole archive	A directory tree	unpack
verify	The whole archive	stdout	verify
ids	The index only	stdout, Zig source	ids
manifest	The index only	stdout, ZON	manifest

Only pack and unpack write to disk. list, ids, and manifest read a few kilobytes at the head of the file; verify and unpack read all of it.

Output streams

Results go to stdout. Errors and usage go to stderr. That split is what makes redirection safe:

zpack ids game.zpak > src/assets.zig       # only the enum lands in the file
zpack manifest game.zpak > manifest.zon

If ids fails, src/assets.zig is empty rather than half an enum with an error message appended.

Exit codes

Code	Means
0	Success, including --help and --version
1	Anything else: a bad argument count, an unreadable path, a corrupt archive, a failed hash

Errors are one line on stderr, naming the operation, the path, and the Zig error:

$ zpack list nope.zpak
zpack: cannot open archive 'nope.zpak': FileNotFound

$ zpack verify damaged.zpak
zpack: 'damaged.zpak' failed verification: HashMismatch

The trailing word is the error name from the library, so every message maps onto the error reference.

Invoking with the wrong number of arguments prints usage to stderr and exits 1. Invoking --help prints the same text and exits 0.

Version

$ zpack --version
zpack 0.0.2

The version comes from build.zig.zon at compile time, so the binary cannot disagree with the package that produced it. The release workflow refuses to publish a tag whose name disagrees with that field.