zarc command-line guide
zarc creates and manages ZAR archives. Build it from the workspace root with
cargo build -p zarlib-cli --release; run cargo run -p zarlib-cli -- <command> during
development, or install it with cargo install --path zarlib-cli.
For an alternate release allocator, build with --features mimalloc.
Get the full command list with:
One-letter shortcuts are shown in the table.
| Command | Shortcut |
|---|---|
create |
c |
add |
a |
remove |
r |
rename (move) |
- |
join |
j |
remove-commits |
- |
convert |
- |
meta |
m |
encrypt |
- |
decrypt |
- |
check |
k |
info |
i |
references |
- |
list |
l |
extract |
e |
For example, zarc a backup.zar new-file.txt is equivalent to
zarc add backup.zar new-file.txt. check uses k to keep c available for
create.
Configuration defaults
zarc reads defaults from the first zarc.json found in this order:
- The current working directory.
- The per-user configuration directory:
$XDG_CONFIG_HOME(or~/.config) on Linux,~/Library/Application Supporton macOS, or%APPDATA%on Windows.
The files are not merged. Use canonical command names as sections and long
option names (without --) as keys:
Use booleans for flags, strings or numbers for single-value options, arrays
for repeatable options, and an integer for the info verbosity level.
Command-line options override the corresponding defaults; explicitly supplied
repeatable options replace, rather than extend, the configured list. Command
aliases use the defaults of their canonical command. Positional arguments
(archive names and input paths), help, and configuration control cannot be
configured. Password flags only select how passwords are read; do not store
passwords in this file. Paths in defaults are relative to the current working directory.
Pass --no-config before or after the command to skip configuration entirely:
Malformed files, unknown options, and invalid settings produce an error instead of silently falling back to another file. Help and version output do not require a valid configuration file.
Common workflows
Rename or move an entry by recording a new commit without recompressing its data:
Create an archive
create makes a new archive and refuses to replace an existing output file by
default. Pass --overwrite to atomically replace an existing archive after the
new archive has been created and validated.
Directories are scanned recursively. Paths inside the current working
directory are stored relative to it; an absolute input outside it is stored
using its basename (for example, /var/log is stored as log). Empty files
are supported.
ZIP, 7z, RAR, ISO, TAR, TAR.GZ, TGZ, and GZ files passed as input are imported by their
internal paths rather than stored as a single archive file. This also applies
to paths passed to zarc add. Encrypted ZIP/7z/RAR sources and ZIP/7z/RAR links are not
supported. Multi-volume RAR archives and RAR special entries are rejected.
ISO import uses ISO 9660 with Rock Ridge preferred over Joliet and the primary
namespace. ISO links and special entries and UDF-only images are not supported.
ISO imports are limited to 100,000 entries, 16 MiB of directory metadata, and
64 directory levels.
TAR symbolic links are preserved where the host supports them, and
hard links are imported as regular files. TAR paths with harmless . components
are normalized; parent traversal and special entries are rejected. Source
archive timestamps are not retained; timestamp options record the staged files' import-time
filesystem timestamps instead. 7z entries using COPY, LZMA/LZMA2, BZip2,
PPMD, DEFLATE, Brotli, LZ4, or Zstandard are supported.
Options:
--block-size SIZE:64Kthrough32M, orauto. The default is 8 MiB;autoselects a size based on available memory.--compression-level LEVEL: Zstandard levels-7through22; default3.--password: prompt without echo and encrypt headers and data blocks.--password-stdin: encrypt using the first line from redirected standard input.--overwrite: replace the target archive if it already exists.--metadata: record supported platform-specific owner, group, and permission metadata.--modification-time,--mt: record each entry's modification time.--creation-time,--ct: record each entry's creation time; fail if it is unavailable for a stored entry.--access-time,--at: record each entry's access time; fail if it is unavailable for a stored entry. Filesystem policies and reads during scanning can affect access times. Timestamps are shown inzarg, but archive extraction does not restore them.--special-files: include named pipes and Unix device nodes; these are otherwise skipped with warnings.--verbose: print the warning when storing a symbolic link. By default, symlinks are stored without this warning.--strict: reject symlinks and unsupported special input types. Without strict mode, symlinks are recorded in the archive and requireextract --symlinksto restore; unreadable files are skipped with a warning; named pipes and device nodes are skipped unless--special-filesis set.--include-file PATTERN/--exclude-file PATTERN(aliases--if/--ef): filter files using fnmatch patterns. Repeat either option to provide multiple patterns.--include-folder PATTERN/--exclude-folder PATTERN(aliases--id/--ed): filter matching folders; matching a folder includes or excludes its entire subtree.--filelist PATH: read patterns from a text file, one per line. Lines beginning with-exclude the pattern; other lines include it. File-list patterns apply to files and folders. Patterns match archive-relative paths with/separators.*,?, and bracket expressions such as[ab]are supported;*can match across/. When any include patterns are provided, unmatched files are omitted. Excludes always override includes. Folder rules in file lists apply to matching folders and their descendants.
The same file, folder, and file-list filters can be used with zarc list to
show only matching archive entries. For example, zarc list backup.zar
--include-file '*.txt' --exclude-folder private lists matching text files
while omitting the private subtree. Unlike extraction, listing does not add
unmatched parent directories to the filtered output.
The scanner deduplicates identical content within the created commit. Some already-compressed formats and media types are stored without another compression pass.
Convert a folder of archives
convert scans only files directly inside the input folder (it does not scan
subfolders) and converts supported ZIP, 7z, RAR, ISO, TAR, TAR.GZ, TGZ, and GZ archives into
separate ZAR files. The fnmatch --filter is matched against each source
filename and defaults to *; unsupported files are ignored. The destination
folder defaults to the input folder. The source archive extension is replaced
with .zar, so backup.tar.gz becomes backup.zar.
Existing destination files are refused unless --overwrite is specified.
When multiple selected source names map to the same output name, that collision
is rejected even with --overwrite. The command continues after an individual
conversion failure, reports each failure, and returns exit code 1 if any
conversion fails or no supported archives match. --block-size and
--compression-level use the same options as create.
Append, remove, and compact commits
meta lists, sets (--set KEY=VALUE) or removes (--remove KEY) custom
key/value metadata. Repeat --set or --remove to change multiple keys.
Values that parse as integers or finite floating-point numbers are stored
numerically; other values are strings. Changes append a metadata-only commit,
so existing commits are not rewritten. Later values override earlier ones,
and removing a key hides its earlier value. Keys starting with zar. are
reserved. meta currently requires an unencrypted archive.
addappends a commit. New or modified paths replace the corresponding entries in the latest TOC; untouched entries remain available.removeappends tombstones. Removing a directory removes its descendants from the effective TOC but does not reclaim historical data.joincompacts an inclusive, contiguous range of commits into one commit at the same position, preserving the resulting TOC state and commits outside the range. Commit IDs are eight hexadecimal digits.remove-commitsremoves the specified commit IDs, preserving the other commits in order. At least one commit must remain; the first can be removed. Use--outputto write a different archive, otherwise the input is replaced. Retained commits are replayed, so removing one can change subsequent state. An incompatible remaining history is rejected when all retained headers are readable. Encrypted headers are copied without passwords and their effects cannot be validated by this command.
Progress bars, speed, and transfer summaries are displayed by default for
create, add, remove, join, check, and extract. Pass --no-progress to suppress
them.
add accepts --block-size, --compression-level, --metadata,
--modification-time (--mt), --creation-time (--ct), --access-time (--at),
--special-files, --strict, --verbose, the include/exclude filter options
above, and --no-progress. Unreadable files are skipped with a warning unless
--strict is set, in which case a permission error fails the operation. Named
pipes and Unix device nodes are skipped with warnings unless --special-files
is set. Device nodes are only created during extraction with extract --devices
and may require privileges. join accepts --from, --to, --block-size,
--compression-level, and --no-progress. The commands stage and validate the
replacement before publishing it. These state-changing operations currently
reject archives whose accumulated TOC depends on encrypted headers; encrypted
archive append/removal/compaction is not supported. remove-commits copies
retained commits without decrypting them and does not require passwords.
Encrypt and decrypt commit ranges
encrypt and decrypt transform the inclusive range of commit IDs in physical
commit order. Without --output, the archive is transformed in place; when
specified, --output FILE (-o FILE) must identify a different path.
encrypt always prompts without echo for the new encryption password. It
accepts --aead and --encryption-scope to select the algorithm and encrypted
content.
For already-encrypted commits in the range, --password prompts for a default
current password and repeatable --password-for COMMIT_ID options prompt for
commit-specific current passwords. Without --strict, selected encrypted
commits that have no supplied current password are preserved unchanged;
--strict makes a missing password an error. A supplied but incorrect password
always fails the operation. For decrypt, --password and --password-for
provide the credentials used to decrypt commits.
Inspect and verify
listdisplays the effective TOC without reading or decompressing block payloads.--to IDshows the state after that commit.infoshows per-commit header content changes, commit IDs, stored sizes, creation date/time, optional username, logical uncompressed file sizes, and the ratio of commit size to uncompressed size. Header-encrypted commits show the uncompressed size as unavailable without credentials.-vadds per-file-group compression and deduplication statistics, plus counts for stored symlinks, pipes, and devices; uselistto see their paths and device numbers.-vvadditionally lists each block's compressed size, compression ratio, file count, and file groups. Both verbose levels read frame metadata without decompressing file contents.--jsonincludes the header content change counts, formatted creation times and Unix-millisecond timestamps, and optional usernames in its machine-readable summary.create --userandadd --userstore the current OS username with the new commit; commit timestamps are always recorded. These statistics use frame metadata and do not verify or decompress data payloads.referenceslists each historical reference as referencing commit, source commit, and archive path.infoincludes per-commit and total reference counts;--jsonusesnullwhen an encrypted header is unavailable. Use--passwordor repeated--password-for IDwith either command to unlock encrypted headers. Removing a source commit is rejected while a retained commit refers to it; the error identifies the references.checkvalidates framing, readable TOC updates, block references, and checksums; it decompresses unencrypted blocks and checks decoded file sizes. Pass--passwordto authenticate/decrypt encrypted content. Without the required password, encrypted portions remain unverified or unreadable.--recoverpermitscheckto scan past damaged framing to a later valid commit. It does not repair or change the file. The command reports recovery warnings and checks the recovered suffix independently.
Extract files
--output DIR (-o DIR) selects the output directory; its default is the
current directory. Extraction plans and validates
the selected archive state, then streams decoded blocks to files and verifies
reconstructed file sizes.
--dry-run: display planned directories and files without writing them.--recheck-block-checksums auto|always|never: control the second block checksum check while writing extracted files. The default,auto, rechecks archives on network drives and older filesystems such as FAT and exFAT. Detection uses the archive's filesystem, not the output directory. If detection fails or the filesystem is unknown, it warns and rechecks.alwaysrechecks on every filesystem;neverdisables this second check. Initial validation, file checksum checks, and encrypted-data authentication remain enabled. Without rechecking, changes after validation may go undetected.--to ID: extract the state as of the selected commit.--collision POLICY: handle archive paths that collide when case-folded:rename(default),first,latest,error, or interactiveask.--existing POLICY: handle files already at the destination:error(default),skip,overwrite, or interactiveask.--metadata: restore supported owner, group, and permissions.--symlinks: create symlinks whose targets remain within the extraction root. This is disabled by default.--devices: create archived Unix character and block devices; privileges may be required.--password: prompt for a password to unlock encrypted headers and blocks.--password-stdin: read the default password from redirected standard input; cannot be combined with--passwordor--password-for.--include-file,--exclude-file,--include-folder,--exclude-folder, and--filelist: select archive-relative paths using the filter rules described above.--no-progress: suppress extraction progress.
ask requires an interactive terminal. Unix extraction uses directory-relative
no-follow operations to guard against symlink traversal and path-component
swaps. The non-Unix fallback uses standard path-based operations and does not
provide equivalent race resistance.
Exit behavior
Successful commands return status 0. The CLI uses distinct nonzero statuses
for usage errors, I/O errors, corrupt framing/container data, and warnings;
check --recover and warning-only unsupported inputs can complete with a
warning status. Treat any nonzero status as requiring attention and read the
reported diagnostic.
Archive paths and encryption
Archive paths are canonical UTF-8 paths separated by /. Absolute paths,
drive prefixes, empty components, . and .. components, NUL bytes, and
backslashes are not stored. During input scanning, entries whose archive path
contains a literal backslash are skipped with a W_INVALID_ARCHIVE_PATH
warning; create --strict fails instead. This preserves portable, unambiguous
archive paths.
Password-encrypted archives use Argon2id for password-based key wrapping and
AES-256-GCM for content encryption. Interactive password prompts require a Unix
terminal and disable echo. For automation, create and extract accept
--password-stdin with redirected input; avoid exposing passwords in shell
history, command arguments, or unprotected files.
Do not treat frame checksums as a security feature: checksums detect accidental
corruption but do not authenticate unencrypted data.