libarchive_oxide-cli 0.1.0

bsdtar-style CLI tools (oxtar/oxcpio/oxcat/oxunzip) over the libarchive_oxide library. Dogfooding + the observation surface for round-trip integration tests.
Documentation

libarchive_oxide-cli

crates.io License: MIT OR Apache-2.0

Four command-line tools over libarchive_oxide. Their interfaces mirror libarchive's bsdtar / bsdcpio / bsdcat / bsdunzip and are drop-in compatible for the supported flag surface below. The ox prefix follows libarchive's own collision-avoidance naming (and the modern Rust-CLI convention of rg/fd/bat), so these never clash with a system tar/cpio/cat/unzip.

cargo install libarchive_oxide-cli
Tool bsd equivalent Role
oxtar bsdtar create/list/extract tar, with gzip/zstd/xz/lz4
oxcpio bsdcpio create/list/extract cpio
oxcat bsdcat transparent decompression to stdout
oxunzip bsdunzip zip extraction (zip64 / AES)

Every tool prints its own contract with --help.

Supported flags

Tool Flags
oxtar -c/-x/-t, -f FILE (-/omit = stdin/stdout), -C DIR, -v, -z/--gzip, -J/--xz, --zstd, --lz4, --format tar|ustar|gnutar|cpio, member operands on -x/-t, --help, --version. Traditional bundled form (oxtar czf a.tgz .) works.
oxcpio -o/-i/-t (and -it = list), -F FILE, -v, -d, member operands on -i/-t. -o reads filenames from stdin.
oxcat [FILE...] (-/none = stdin), --help, --version.
oxunzip -l, -d DIR, -o, -P PASSWORD, member operands, --help, --version.

Reads always auto-detect compression (gzip/zstd/xz/lz4) and format (tar/cpio/ar/zip/7z/iso).

Exit codes (unified across all four tools)

Code Meaning
0 success
1 runtime failure (I/O error, corrupt archive, decompression-bomb cap hit)
2 usage error — bad, unknown, or unsupported flag; missing operand

Intentionally unsupported (fails with exit 2 — never a silent no-op)

Classic flags the library cannot honor faithfully return unsupported: <flag> rather than pretending to work. This is a deliberate debt-exclusion policy, not an oversight:

  • oxtar -j / --bzip2 — bzip2 is not supported by the library; recompress with -z/-J/--zstd/--lz4.
  • oxtar -r / -u — append/update. Rewriting an existing archive's trailer is out of scope for the 0.x line; build afresh with -c.
  • oxcpio -p (pass-through copy), -C (I/O block size).
  • oxunzip -n (never-overwrite), -x (exclude).
  • Any other classic flag → unknown flag.

No nonstandard "modern-only" flags of our own invention are added.

Safe defaults (a documented divergence from historical tar)

Because these tools are built to consume untrusted archives, two safety nets are on by default — unlike classic tar:

  • Path-traversal rejection — entries whose path escapes the destination (../, absolute, drive/UNC) are refused.
  • Decompression-bomb cap — transparent decompression is capped at 4 GiB.

SemVer: the CLI interface is the contract

For this crate, the command-line interface is the public API, and it is what SemVer governs. Concretely:

  • Major (breaking): removing or renaming a flag or subcommand, changing a flag's meaning, changing an exit code for an existing condition, or altering the parseable shape of stdout for a given invocation.
  • Minor (additive): adding a new flag, accepting a new input format, or adding output that does not change existing lines.
  • Patch: bug fixes that make behavior match the documented contract.

The bsd* interfaces these tools track are themselves long-frozen, so churn is expected to be minimal. The internal library API (libarchive_oxide) has its own, separate SemVer surface. See CONTRIBUTING.md for the full stability policy and the path to 1.0.

License

Licensed under either of MIT or Apache-2.0 at your option.