zipnative-cli — Command-line reference

zipnative-cli 1.0.0 is the official command-line interface for the zipnative engine — fifteen commands over stdin/stdout pipelines, an agent-native automation contract (a --json envelope carrying the engine's err.code verbatim, --dry-run, --summary / --fields projection, JSON Schemas), and the one job the engine refuses by design: writing to the filesystem. Offline, always. Pins zipnative ^1.0.0.

zipnative-cli is a pure dispatch layer over zipnative: no ZIP logic lives in the CLI, every command forwards to a public engine API, and the engine's guarantees — safe-by-default extraction, deterministic bytes, the frozen 39-code error vocabulary — arrive unchanged. What the CLI adds is the process boundary the engine deliberately lacks: files, directories, pipes, exit codes, shell completion, and a JSON contract that agents and CI can drive without parsing prose.

Installation#

# Run directly with npx — no global install required
npx zipnative-cli list archive.zip

# Or install globally: the binary is called `zipnative`
npm install --global zipnative-cli
zipnative list archive.zip

Requirements: Node.js ≥ 22. The package has exactly one runtime dependency, zipnative ^1.0.0, ships as a single CommonJS binary, and is published with npm provenance — verify the artefact with npm audit signatures. Every command runs offline: no command can open a socket.

When to use the CLI#

The three surfaces share one engine, so the artefacts are interchangeable; the choosing guide holds the full capability × surface matrix.

Quick start#

# A reproducible archive: identical SHA-256 on every runtime
zipnative create src/ docs/ --output release.zip --deterministic

# Inventory without decompressing a byte
zipnative list release.zip --format json | jq '.entries[].name'

# A CI gate: fail (exit 1, E_CHECK_FAILED) unless every assertion holds
zipnative inspect release.zip --check deterministic,no-encryption,safe-names,max-entries=1000

# Extract behind the default guards — zip-slip, symlinks, bombs, duplicates refused
zipnative extract --input release.zip --output-dir ./out

# Integrity in one call (never fails for an archive problem — it reports)
zipnative verify release.zip --json

The agent contract#

The CLI is designed to be driven by programs — CI runners, coding agents, other languages — without parsing prose.

• stdout is the artefact, stderr is the channel. Archive bytes, entry bytes, reports, schemas and scripts go to stdout. Diagnostics, progress and — under --json — the status or error envelope go to stderr, as the last line that starts with {. batch is the one exception: its JSON report is the stdout document.
• Stable error codes. Every failure is one of 13 E_* classes (E_USAGE exit 2; E_INPUT, E_PARSE, E_IO, E_SECURITY, E_DATA, E_LIMIT, E_UNSUPPORTED, E_NOT_FOUND, E_VERIFY_FAILED, E_CHECK_FAILED, E_POLICY, E_RUNTIME exit 1) and the envelope carries the engine's ZIP_* code verbatim as zipCode, the entry name when one is involved, a detail object and a remedy string. Branch on the codes, never on message text.
• Exit codes: 0 success (also a closed pipe), 1 any E_* class but usage, 2 usage error, 130 / 143 interrupted by SIGINT / SIGTERM (only the file being written is removed; finished outputs stay).
• --dry-run on create, extract, modify, stream, cat, inflate and batch validates and prints the plan, writing nothing.
• Token economy: --summary returns a minimal verdict and --fields a,b.c projects dot paths, on list, inspect, verify, stream and batch.
• Schemas: zipnative schema <subject> prints a JSON Schema (Draft 2020-12) for every input and output shape, and zipnative schema manifest the capability manifest — commands, flags, codes, limits — that this page and the CLI playground are checked against.
• Config: .zipnativerc.json is discovered upward from the working directory (global keys plus command-scoped sections; explicit flags win). Unattended runs should pass --no-config or --config <file>. The codec key is refused from any config file — a codec module executes code.
• Parsing rules: flags and positionals are order-independent; a boolean flag never consumes the next token; --flag=false|0|no|off is the explicit off form; a lone - means stdin or stdout; combined short flags (-lq) are refused. Short aliases taking a value: -i, -o, -d, -e, -f; boolean: -q, -h, -V.

A status envelope and an error envelope, as an agent sees them. The error message is the CLI's short context, a colon, then the engine's own message verbatim; remedy is the exact string from the remedy table below (message wording is not a contract — the codes and remedy are):

{"ok":true,"command":"create","dryRun":false,"output":"release.zip","entries":42,"files":40,"directories":2,"bytes":183044,"bytesIn":611203,"method":"deflate","level":6,"deterministic":true,"tier":"pure-pinned","order":"canonical","stream":false,"layout":"buffered","parallel":false,"skipped":[],"diagnostics":[]}
{"ok":false,"command":"extract","error":{"code":"E_SECURITY","message":"Failed to extract: zipnative: entry name '../../etc/passwd' escapes the extraction root (zip-slip, CWE-22) — this archive is hostile or corrupt; pass rejectTraversal: false to skip such entries instead","zipCode":"ZIP_PATH_TRAVERSAL","entryName":"../../etc/passwd","remedy":"--skip-unsafe (extract, stream)"}}

Without --json the same failure prints the message line and then a remedy: … line on stderr, with the same text.

Refused combinations (exit 2, E_USAGE)#

Usage errors are detected before any I/O, so a refused combination never leaves a partial file behind. Beyond the obvious (an unknown flag, a malformed value, a missing required flag), the CLI refuses:

--config together with --no-config is not refused: --no-config wins and the named file is never read.

Error classes, codes and remedies#

The engine's 39 frozen ZIP_* codes map to the CLI's E_* classes by a fixed table (zipnative schema errors prints it; a core release that added a code would fail the CLI's own type-check rather than leak as E_RUNTIME). Grouped by class:

E_IO, E_VERIFY_FAILED and E_POLICY carry no ZIP_* code: they are the CLI's own (a filesystem error, a verify verdict, a governance violation). A node:zlib failure on the sync path is mapped to the same codes the pure tier would raise (Z_DATA_ERROR → ZIP_DEFLATE_CORRUPT, Z_BUF_ERROR → ZIP_DEFLATE_TRUNCATED), so the class never depends on the codec tier.

Remedies. The engine's messages name library options that do not exist on a command line, so the envelope adds remedy — the flag or command that lifts the refusal. The table is fixed; a code absent from it has no remedy (structural refusals, corrupt data, usage errors). One exception: a ZIP_LIMIT_EXCEEDED names its bound, and the remedy is then the exact flag, --max-<bound> <value> (raise the bound for trusted input only; "none" disables it).

Diagnostics. The engine's eleven diagnostic codes are informational — they ride in the envelope's diagnostics[] and are never thrown unless --strict (when the first one becomes E_CHECK_FAILED, or E_VERIFY_FAILED under verify): ZIP_PREPENDED_DATA, ZIP_MULTIPLE_EOCD, ZIP_NAME_MISMATCH, ZIP_UNICODE_PATH_CONFLICT, ZIP_INVALID_UTF8_NAME, ZIP_DUPLICATE_NAME, ZIP_EXTRA_FIELD_MALFORMED, ZIP_ZIP64_EXTRA_IGNORED, ZIP_TIMESTAMP_NOT_PINNED, ZIP_NONDETERMINISTIC_CODEC, ZIP_DEAD_BYTES_RATIO. The errors guide explains each code and each diagnostic.

Command reference#

Fifteen commands in four groups. Every command accepts the global options; the tables below list the command-specific flags.

Create & modify#

zipnative create#

Build a deterministic ZIP from files, directories, stdin or a manifest.

zipnative create [<path>...] --output <out.zip> [options]
zipnative create --from-manifest <entries.json> -o <out.zip>
cat file | zipnative create --stdin-name <name> -o <out.zip>

The status envelope reports entries, files, directories, bytes, bytesIn, method, level, deterministic, tier, order, stream, layout, parallel, skipped and diagnostics. A --stream archive is reproducible but not canonical (data descriptors) — inspect --check canonical-layout tells the two apart.

zipnative modify#

Incremental edits without recompressing untouched entries.

zipnative modify --input <a.zip> --output <b.zip> [edits] [--compact]
zipnative modify --input <a.zip> --in-place [edits]
zipnative modify --input <a.zip> -o <b.zip> --from-manifest <edits.json>

Edits apply in a fixed order regardless of argv order: remove → rename → replace → add / add-dir → comment. The default save is append-only: original bytes verbatim, edits appended, a new central directory — removed or replaced content remains recoverable (data remanence), and 7-Zip's CLI is known to mis-read this layout. Pass --compact when either matters. Every untouched entry is verified (CRC-32, sizes, local header against central directory) before it is re-emitted; a lying record is refused with E_DATA / E_SECURITY and the entry name. Encrypted entries are copied as-is and counted in verifySkipped.

Read & extract#

zipnative list#

List archive entries without decompressing anything.

zipnative list --input <a.zip> [options]
zipnative list <a.zip> --format ndjson --include '**/*.json'

JSON shape: zipnative schema entries.

zipnative inspect#

A forensic report with determinism and security assertions — the CI gate. The archive is opened eagerly: every local header cross-checked, the overlap table built up front.

zipnative inspect --input <a.zip> [--format json|text] [--check <assert>]...
zipnative inspect <a.zip> --check deterministic,no-encryption,safe-names --json

The --check vocabulary — fifteen simple assertions and six that take a value (canonical-layout and no-data-descriptor are aliases, so twenty distinct checks):

JSON shape: zipnative schema inspect.

zipnative cat#

Stream one or more entries to stdout.

zipnative cat --input <a.zip> --entry <name> [--entry <name>]... [-o <file>]
zipnative cat <a.zip> <name> [<name>...]

The CRC is verified at the end of the stream (like unzip -p), so stdout may already carry bytes when E_DATA fires; with --output the partial file is removed.

zipnative extract#

Extract to a directory, secure by default — the CLI is the filesystem trust boundary the engine refuses to be.

zipnative extract --input <a.zip> --output-dir <dir> [options]
zipnative extract release.zip -d ./out --dry-run --json

Refusals are E_SECURITY with the engine code: ZIP_PATH_TRAVERSAL, ZIP_SYMLINK_REJECTED, ZIP_EXTRACT_DUPLICATE_PATH, ZIP_ENTRY_OVERLAP, ZIP_CD_LFH_MISMATCH. Bounds are E_LIMIT (--max-entry-size, --max-total-size, --max-ratio, …).

zipnative stream#

The forward-only reader for unseekable input — stdin, pipes, a download in flight. No central directory is consulted.

curl ... | zipnative stream [--list] [--format ndjson]
curl ... | zipnative stream --output-dir <dir>
cat a.zip | zipnative stream --cat <name>

Trust caveat: local headers alone — there is no central directory to cross-check names, sizes, methods or attributes, so --preserve-mode, --allow-symlinks and --skip-symlinks are unavailable here, a warning: line is printed at start, and every JSON output carries trust: "local-headers-only". Prefer list / extract whenever the whole file is available.

Integrity & codecs#

zipnative verify#

Deep integrity verification in one call — the engine's ZipVerificationReport verbatim.

zipnative verify --input <a.zip> [--format json|text] [--strict]
zipnative verify <a.zip> --entry manifest.json --json

The report is { ok, error, entryCount, entries[{ name, ok, crcMatch, sizeMatch, localHeaderMatch, skipped? }], diagnostics } plus failed, skipped and strict; selected (the requested names) is present only under --entry. Without --entry the report is verifyZip() verbatim; with it, the CLI opens the archive eagerly (the same structural pass) and calls verifyEntry() on each name, so a structural refusal lands in error exactly as it would from verifyZip(). Encrypted entries are honestly skipped, never faked as verified. Exit 1 / E_VERIFY_FAILED when ok is false; --strict also fails on any diagnostic. verify proves integrity and structure, not path safety: a zip-slip archive with valid CRCs is ok — gate names with inspect --check safe-names,no-symlinks or extract --dry-run before extracting.

zipnative crc32#

CRC-32 (IEEE, the ZIP checksum) of files or stdin, in 64 KiB chunks.

zipnative crc32 [<file>...] [--seed <hex>] [--expect <hex>] [--format text|json]

zipnative inflate#

Decompress a raw DEFLATE (RFC 1951) or registered-codec stream through the engine's resumable inflater — constant memory, exact bytesConsumed, trailing bytes reported as leftover.

zipnative inflate [--input <file>] [--output <file>] [--max-output <size>]

Errors: ZIP_DEFLATE_CORRUPT / ZIP_DEFLATE_TRUNCATED → E_PARSE, ZIP_INFLATE_OUTPUT_OVERFLOW → E_DATA.

Automation & meta#

zipnative batch#

Batch orchestration in two modes.

zipnative batch --input-dir <dir> --output-dir <dir> [--task create] [create flags]
zipnative batch --input-dir <dir> --task verify
zipnative batch --manifest <tasks.json> [--continue-on-error] [--allow-codec-load]

Under --json stdout is one batch document — each task's stdout is captured into tasks[i].report (parsed JSON / NDJSON) or .stdout, so create / modify / cat / inflate tasks must declare an output and stream --cat is refused at validation. Path values inside a manifest are data and are refused on ... Exit 1 carries the first failing task's E_* code.

Manifest rules (validated in full before any task runs):

• The document is { "version": 1, "tasks": [ … ] } — version must be exactly 1, tasks a non-empty array of at most 1000 objects.
• Each task is { id, command, flags? }. id is a non-empty string of A–Z a–z 0–9 _ -, unique within the manifest; command is one of the ten whitelisted commands (batch, govern, schema, completion and doctor are named as never allowed); flags is an object keyed by bare flag names (no leading dashes, no whitespace or =).
• Flag values are string, number (finite; rendered as text), boolean (true emits the bare flag, false omits it) or string[] (a repeatable flag). Anything else is refused.
• Relative values of the path flags (input / i, output / o, output-dir / d, from-manifest, base, and the path half of add / replace) resolve against the manifest file's directory after the same traversal check argv paths get; - is left alone.
• A value @<id> is substituted with the resolved output (else output-dir) of an earlier task; a forward or unknown reference, or a reference to a task that declares neither, is refused.
• A codec flag in any task needs --allow-codec-load on the batch invocation.
• Structural violations (shape, types, version, the task cap) are exit 2 / E_USAGE; value violations (a bad or duplicate id, a command outside the whitelist, a bad @ reference) are exit 1 / E_INPUT; a manifest that is not JSON is E_PARSE.

zipnative doctor#

Environment and capability preflight — always offline.

zipnative doctor [--format json|text]

Ten checks: cli, node (≥ 22), zipnative (package vs VERSION export), deflate-tier (node-zlib expected; pure under --pure-codecs), deflate-pinned (the tier --deterministic uses), web-streams, workers (for create --parallel), codecs, limits (the effective bounds, --max-* overrides included) and commands. Statuses ok, warn, error; exit 0 when every check passes, 1 otherwise.

zipnative schema#

Print a JSON Schema (Draft 2020-12) or the capability manifest.

zipnative schema [<subject>]     # default subject: create-manifest
zipnative schema list            # { subjects: [...] }
zipnative schema manifest        # commands, flags, codes, limits, schemas

Twenty-two subjects: inputs create-manifest, modify-manifest, batch-manifest; outputs entries, entries-summary, inspect, inspect-summary, verify, verify-summary, stream, stream-summary, batch, batch-summary, doctor, govern-verify, crc32; the envelopes status, error; errors (the E_* codes, the 39 ZIP_* → E_* mapping and the diagnostics); limits, diagnostics; and manifest. Every $id is versioned: https://zipnative.dev/schema/cli/1.0.0/<subject>.schema.json.

zipnative completion#

Emit a shell completion script, generated from the same command table as --help and schema manifest.

zipnative completion bash > /etc/bash_completion.d/zipnative
zipnative completion zsh  > "${fpath[1]}/_zipnative"
zipnative completion fish > ~/.config/fish/completions/zipnative.fish
zipnative completion powershell >> $PROFILE     # `pwsh` is accepted as an alias

Path flags (--input, --output, --output-dir, --input-dir, --base, --from-manifest, --manifest, --config, --codec, --comment-file) complete files; other value flags require an argument; boolean flags take none. The shells are bash, zsh, fish and powershell (pwsh emits the same PowerShell script); anything else is exit 2.

zipnative govern#

The AI-governance / human-in-the-loop contract.

zipnative govern rules                    # the human/agent protocol
zipnative govern policy [--pretty]        # the machine-readable policy (JSON)
zipnative govern verify-issue <draft.md>  # validate a draft; exit 1 / E_POLICY on violation

verify-issue fails a draft that proposes a runtime dependency or omits a reproduction; missing recommended fields and apparent anti-goal proposals (encryption, other formats, multi-disk, repair) are warnings. A passing check is necessary, never sufficient — agents are draftsmen; a human reviews and submits.

Global options#

Value grammars. A <size> is a decimal integer with an optional binary suffix k, m, g or t (case-insensitive), optionally followed by i, b or ib — 65536, 512k, 1m, 8g, 1t, 1GiB and 4gb are all binary multiples; none, inf and infinity disable the bound (a visible warning for every --max-* flag). A count (--max-entries, --max-ratio, --check max-entries=N, min-entries=N, max-ratio=N) is a plain non-negative integer or the same three words — a k / m / g suffix is refused there. Every --max-* bound, --max-input-size and inflate --max-output refuse 0 (use none). The eight --max-* flags are the engine's ZipLimits; --max-input-size is the CLI's own.

Configuration file#

.zipnativerc.json is looked up by walking upward from the working directory (the nearest file wins) unless --config <file> names one — in which case discovery is skipped and a file that does not exist is exit 2 — or --no-config disables the mechanism (then --config is ignored). The file must be a JSON object of at most 1 MB; invalid JSON, a non-object, or a larger file is exit 2. Top-level keys are bare flag names with global scope; a key that names a command and holds an object is that command's section, and a command-scoped value wins over a global one. Numbers are coerced to strings ("level": 9 ⇒ --level 9), arrays of strings or numbers become repeatable flags, booleans are flags; null or nested objects are ignored. Config only fills flags you did not pass — an explicit flag, even a boolean, is never overridden. codec is refused from any file, in any section, whether or not the section is for the running command.

{
  "no-color": true,
  "max-total-size": "32g",
  "create": { "deterministic": true, "level": 9 },
  "extract": { "overwrite": true }
}

Environment#

Output is English and locale-independent: no locale is read, dates are ISO-8601 UTC, sizes use binary units, and messages are not part of the contract — branch on error.code, error.zipCode and error.remedy.

Security posture#

• Offline, always. No command can open a socket — no telemetry, no update check, no URL from any argument.
• The extraction sink re-checks every name with the engine's sanitizeEntryPath() and contains it under --output-dir; nothing unsafe is ever written, with or without --skip-unsafe. Symlinks are never materialised.
• Bounds are on by default and every one is named and CWE-tagged; none is loud. inflate has a hard output bound; --max-input-size caps every buffered read.
• Overwrite is refused (E_IO) unless --overwrite; interrupts remove only the file in flight.
• --codec executes user code, so it is accepted on the command line only — never from .zipnativerc.json, and only inside a batch manifest under --allow-codec-load.
• Manifest paths are data. .. inside a create / modify / batch manifest is refused (E_INPUT); argv paths are the invoking user's own authority.

Conformance#

Every archive the CLI writes is ISO/IEC 21320-1:2015 conformant: the CLI repository runs its own veraZIP gate — the engine's clause-by-clause validator over a corpus of archives produced by the CLI, plus foreign integrity passes — blocking in CI and before every publish. The conformance guide explains the gate; conformant is not the same as safe, which is why the extraction guards exist on top.

Not supported#

Versioning#

SemVer over the fifteen commands and their flags, the exit codes, the thirteen E_* classes and the ZIP_* → E_* mapping, the envelope and report keys, the schema subjects, the .zipnativerc.json keys, the ZIPNATIVE_* variables — and the bytes written under --deterministic (a byte change is semver-major, as for the engine). Message wording, layout and key order are not a contract.

Further reading#

• CLI playground — assemble any of the fifteen commands with live validation and copy the result.
• Choosing your surface — library, CLI or MCP server, per capability.
• MCP guide — the same engine for AI assistants.
• Security model · Errors and error codes · The determinism contract.
• docs/data/cli-surface.json — the command and flag snapshot this page is verified against; the full README, AGENTS.md and samples live in the zipnative-cli repository.