Argument reference

What each argument means, and what it changes.

This page is the practical reference for `pack()` and `unpack()`. It explains how each argument affects source selection, write behavior, ESM and CommonJS usage, return values, dry runs, updates, and extraction safety.

pack()

`pack()` creates archive output from in-memory data, glob-expanded paths, or exact filesystem paths. Native `.nar` is the default, and you can also target `.zip`, `.tar`, `.tgz`, `.tar.gz`, or `.gz` output when that fits the workflow better. The package entry point supports both ESM `import` and CommonJS `require()`.

What it returns

Without `destinationPath`, `pack()` returns archive bytes as a `Uint8Array`.

With `destinationPath`, `pack()` writes to disk and returns `undefined` unless `passThru` is enabled, in which case it returns an `ArchiveSummary`. The final output format comes from `outFormat` or from the destination extension when it is recognized.

Arguments

blob

Meaning: an in-memory source.

Effect: packs a string, `Blob`, typed array, `ArrayBuffer`, `SharedArrayBuffer`, or other byte-like input directly into a single-file archive.

CLI: no direct flag. The terminal interface is file-oriented, so use the package API when the source only exists in memory.

path

Meaning: one glob or an array of globs.

Effect: expands through `fast-glob`, so patterns such as `src/**/*.ts` are resolved before the archive is built.

CLI: --path or -p. The first source path can also be passed positionally.

literalPath

Meaning: one exact path or an array of exact paths.

Effect: bypasses glob semantics. Use it when you want the path names you pass to be treated literally.

CLI: --literalPath or -l. Repeat the flag for multiple exact inputs.

destinationPath

Meaning: where the archive file should be written.

Effect: switches `pack()` from memory mode into filesystem mode. Combined with `whatIf`, it plans the write without creating the archive file. The extension can also infer the output format for `.zip`, `.tar`, `.tgz`, `.tar.gz`, and `.gz`.

CLI: --destinationPath or -d. It is also accepted as the second positional argument.

outFormat

Meaning: the archive format to emit.

Effect: overrides the default `.nar` output and selects `zip`, `tar`, `tgz`, `tar.gz`, or `gz`. When both `destinationPath` and `outFormat` are provided, they must agree on the format family.

CLI: --outFormat or -o.

compressionLevel

Meaning: gzip policy for the resulting archive.

Effect: accepts `Optimal`, `Fastest`, or `NoCompression`. Higher compression usually trades more CPU for fewer bytes. It applies to `.nar`, `.zip`, `.gz`, `.tgz`, and `.tar.gz` output.

CLI: --compressionLevel or -c.

update

Meaning: merge into an existing `.nar`.

Effect: reads the current archive at `destinationPath`, keeps entries that are not being replaced, and overwrites entries whose paths are present in the new input set. This is limited to native `.nar` output.

CLI: --update or -u.

force

Meaning: allow overwriting the destination file.

Effect: lets `pack()` replace an existing archive instead of failing with `ARCHIVE_DESTINATION_EXISTS`.

CLI: --force or -f.

passThru

Meaning: request a summary object.

Effect: returns an `ArchiveSummary` describing entry count, output mode, bytes, destination, and dry-run status.

CLI: --passThru or -t.

whatIf

Meaning: dry-run mode.

Effect: computes the archive and summary without writing the archive file to disk.

CLI: --whatIf or -w.

confirm

Meaning: reserved switch.

Effect: currently unsupported. Passing it throws `ARCHIVE_CONFIRM_UNSUPPORTED`.

CLI: --confirm or -y.

Practical examples

Filesystem output pack() 
await pack({
  literalPath: ['src', 'package.json'],
  destinationPath: './dist/app.nar',
  force: true,
})
In-memory output pack() 
const archive = await pack({
  blob: 'hello world',
})
Alternative output formats pack() 
await pack({
  literalPath: ['src'],
  destinationPath: './dist/app.zip',
  outFormat: 'zip',
})

await pack({
  literalPath: ['src'],
  destinationPath: './dist/app.tgz',
})
Terminal, long flags nar pack 
nar pack --path ./src --destinationPath ./dist/app.nar --force --passThru
nar pack --path ./src --destinationPath ./dist/app.zip --outFormat zip
nar pack --literalPath ./package.json --destinationPath ./dist/meta.nar
nar pack --path ./src --path ./README.md -d ./dist/bundle.nar -c Fastest
Terminal, short flags nar pack 
nar pack -p ./src -d ./dist/app.nar -f -t
nar pack -p ./src -d ./dist/app.zip -o zip
nar pack -l ./package.json -d ./dist/meta.nar
nar pack ./src ./dist/app.nar -u -w

unpack()

`unpack()` reads archive data and either returns it in memory or writes the extracted files to disk. It reads native `.nar` payloads and also incoming `.zip`, `.tar`, `.tgz`, `.tar.gz`, and `.gz` archives. The same entry point is available from ESM `import` and CommonJS `require()`.

What it returns

Without `destinationPath`, `unpack()` returns a `Uint8Array` when the archive contains a single file, or an `UnpackedArchive` object when multiple entries are present.

With `destinationPath`, `unpack()` writes files to disk and returns `undefined` unless `passThru` is enabled, in which case it returns an `ArchiveSummary`.

Arguments

blob

Meaning: an in-memory archive source.

Effect: unpacks bytes already held by your code without touching the filesystem for the read step.

CLI: no direct flag. Use the package API when the archive is already in memory.

path

Meaning: a source archive path.

Effect: reads the archive from disk with standard path semantics. For `unpack()`, this is a single string, not a glob array.

CLI: --path or -p. The source archive can also be passed as the first positional argument.

literalPath

Meaning: an explicit source archive path.

Effect: mirrors the `path` slot but lets the caller stay consistent with code that already uses `literalPath` naming.

CLI: --literalPath or -l.

destinationPath

Meaning: extraction target directory.

Effect: switches from returning memory results to writing the extracted directory tree on disk.

CLI: --destinationPath or -d. It is also accepted as the second positional argument.

force

Meaning: allow overwriting extracted files.

Effect: replaces existing files in the destination tree rather than failing when a target path already exists.

CLI: --force or -f.

passThru

Meaning: request an extraction summary.

Effect: returns `ArchiveSummary` instead of `undefined` when writing to disk.

CLI: --passThru or -t.

whatIf

Meaning: dry-run mode.

Effect: validates and plans the extraction without writing any files. Useful for previews and CI checks.

CLI: --whatIf or -w.

confirm

Meaning: reserved switch.

Effect: currently unsupported. Passing it throws `ARCHIVE_CONFIRM_UNSUPPORTED`.

CLI: --confirm or -y.

Practical examples

Extract a nodearchive payload unpack() 
await unpack({
  path: './dist/app.nar',
  destinationPath: './out',
  force: true,
})
Extract an incoming zip or tarball unpack() 
await unpack({
  path: './vendor/release.zip',
  destinationPath: './vendor/release',
  force: true,
})
Terminal, long flags nar unpack 
nar unpack --path ./dist/app.nar --destinationPath ./out --force --passThru
nar unpack --literalPath ./vendor/release.zip --destinationPath ./vendor/release
nar unpack --path ./incoming.tar.gz --destinationPath ./preview --whatIf
Terminal, short flags nar unpack 
nar unpack -p ./dist/app.nar -d ./out -f -t
nar unpack -l ./vendor/release.zip -d ./vendor/release
nar unpack ./incoming.tar.gz ./preview -w