libarchive_oxide-cli
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.
| 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.