ZArchiveSharp.Cli 1.4.0

ZArchiveSharp.Cli

Command-line tool for creating and extracting ZArchive (.zar) files using ZArchiveSharp — pack a directory, extract an archive, convert Xbox ISOs (XISO), or batch-process a folder in parallel.

A pure-C# port of the zarchive.exe contract (ZArchive 0.1.2): same arguments, defaults, stdout chatter and exit codes, with three documented deviations where native behavior is a bug.

The global tool command is zar. Standalone release bundles (release_<version>_<rid>.zip) ship the same CLI as ZArchiveSharp (ZArchiveSharp.exe on Windows), are framework-dependent (matching .NET runtime required), and always print the name they were launched as in help and usage text — swap zar for ZArchiveSharp in the examples when using those bundles.

Install

dotnet tool install -g ZArchiveSharp.Cli

Usage

zar [options] [input] [output]

Outputs default to <stem>.zar / <stem>_extracted next to the input, like zarchive.exe. Args are exactly input [output] — extras fail with -1 / Too many paths specified, never silently dropped. -o/--output occupies the output slot, so zar in -o out extra is a usage error.

Batch mode (-b/--batch) processes every processable file directly inside the input directory (one level, not recursive): archives (.zip/.rar/.7z/.tar/.gz via an installed 7z, --seven-zip override) → ISO/dir → .zar; --mode auto/extract-archive/extract-iso/compress selects the legs, --keep-originals/--delete-source (default keep) controls cleanup, and --policy (fail/skip/overwrite/auto-rename) applies to batch collisions only. Sources are deleted only after the terminal .zar stage succeeded, and same-stem archives are isolated so parallel items never race. A batch whose only failures are collision refusals exits -11.

Options

  -l, --level <N>       Compression level 1-22 (default: 6)
      --dict <file>     Dictionary file (pack/zstd; never stored)
      --check/--no-check  Write/omit content checksums
  -j, --jobs <N>        Parallel workers: batch items plus 64 KiB block fan-out inside a single pack/extract, capped by CPU, byte-identical (default: 4)
  -p, --policy <P>      Collision policy: fail, skip, overwrite, auto-rename
  -b, --batch           Batch process all files in input directory
      --mode <M>        Batch stages: auto, extract-archive, extract-iso, compress
      --seven-zip <exe> 7z binary for the archive stage
      --keep-originals/--delete-source  Batch source cleanup (default: keep)
  -o, --output <path>   Output path
  -q, --quiet           Suppress output
      --no-compress     Store blocks without compression
      --no-telemetry    Disable usage stats, update checks and bug reports
  -v, --version         Show version
  -h, --help            Show this help

-- ends option parsing everywhere — including inside zar zstd and zar seekable — so paths that begin with - stay reachable. Unknown options are usage errors (-1), value options must not be followed by another known option, but other dash-prefixed values are accepted as paths (zar -o -out.zar src, zar --iso -game.iso out.zar). zar -o game.zar without an input and --iso combined with --batch are usage errors.

Examples

# Pack (zstd level 6 by default, deterministic order)
zar C:\game C:\game.zar

# Maximum compression
zar -l 19 C:\game C:\game.zar

# Extract
zar C:\game.zar C:\game_out

# Convert an Xbox ISO
zar --iso C:\game.iso C:\game.zar

# Batch-pack every processable file under C:\games with 8 workers
zar -b -j 8 C:\games C:\archives

Exit Codes

Identical to zarchive.exe (-2 and -5..-9 are unused upstream too):

Format Notes

• .zar is the ZArchive 0.1.2 format: 64 KiB blocks, each independently zstd-compressed (raw fallback when compression does not shrink), big-endian structures, Windows-1252 names, footer SHA-256
• Compression is byte-identical to libzstd 1.5.7; archives interop with zarchive.exe both ways
• No native dependencies, no unsafe, trimmable and AOT-compatible

Error Reporting

All logging flows through Serilog. Warnings and errors are also forwarded to the PureLogicCode bug-report API with environment, error, and exception details (background sender, at most 9 reports/minute, best-effort flush bounded to well under a second at exit, never crashes the CLI; user profile and account name are redacted). Each launch also records one anonymous usage hit with the PureLogicCode ApplicationStats API (rate-limited server-side to 1/hour/IP), and a background GitHub check announces newer releases with a bounded (15 s) optional browser prompt. Pass --no-telemetry, or set ZAR_BUG_REPORT=off, to disable all outbound telemetry; --help/--version launches never send anything.

Documentation

Full documentation lives in the repository wiki (docs/): format spec, compression guide, pipeline API, benchmarks and FAQ. Release notes: WhatsNew.md and docs/release-notes.md.

License

MIT — see LICENSE. The zar CLI incorporates permissively licensed components; their notices are listed in THIRD-PARTY-NOTICES.md.