CLI reference

CLI reference

Use bd-archive --version to identify an installation. bd-archive --help lists commands; each command's --help describes its arguments.

create

bd-archive create -s SOURCE -n NAME -o OUTPUT [options]

Prepares disc folders and shows a preview before confirmation. Raw mode is the default: it plans the source across discs, builds one disc from the selected units and finally offers to remove them from the source (default: no).

Option	Default	Meaning
-s, --source	Required	Source directory, including subdirectories; raw mode archives whole units from it on one disc
-n, --name	Required	Archive name; see rules below. Raw mode uses it as volume label and as the folder holding the files on the disc
--description	Empty	Optional free-text description in each generated README (RAW and DAR)
-o, --output	Required	Persistent output; raw writes disc/ and manifest.json, DAR writes folders into discs/
--iso	Off	Write ISO images under images/ instead of disc folders
-m, --mode	raw	raw or dar
-w, --workdir	<output>/.bd-archive-work/	Dedicated temporary storage
-D, --device	Auto-detect	Drive for capacity detection
-b, --bytes	Detected from disc	Manual capacity in bytes; no drive needed
-r, --redundancy	5	Whole percentage 0–100 of the data, or a fixed size per disc (500M, 2G); 0 or none disables PAR2. The rest of the disc stays free
--fill-recovery	Off	Also fill each disc's remaining free space with PAR2 data; skipped on a disc where it adds less than 0.5% of its data. -r 0 --fill-recovery uses only the free space; not allowed with -r none
-y, --yes	Off	Build after the preview without asking. Raw mode selects the most ordered plan and never removes archived units from the source
-h, --help	—	Show mode-grouped help

Names are 1–27 ASCII characters: start with a letter or digit, then use letters, digits, ., _, + or -. Names may not contain -catalog or end in -gen<N> with a numeric N. Spaces and umlauts are not accepted. Keep the same name throughout an incremental chain.

Use --description for longer text, including spaces, Unicode and line breaks. It appears as DESCRIPTION below the archive name in each generated README. There is no application-defined length limit. The description does not change archive filenames, volume labels or chain identity; omitting it omits the field. For example:

bd-archive create -s ./photos -n Photos2026 -o ./archive \
  --description "Family photos and videos from summer 2026"

Both modes reject multiple hardlink names within the selected source tree, including with --iso; raw mode also rejects hardlinks between the source and an attachment. The check uses filesystem and inode identity, not file content or the total link count. Links outside these trees are irrelevant; independent copies and reflinks are allowed. DAR auto-deferred paths do not count.

Raw options

Option	Default	Meaning
--group-by	depth:1	depth:N keeps each folder N levels below the source whole; depth:inf separates every file
--order-by	name	name (relative path), mtime (modification time) or content-date (metadata date via ExifTool; modification time without one)
--max-free	Off; include all	Permit deferring the last units in fill order; limit the unused data budget on every disc of a plan with 5 (percent), 500M or 2G (decimal units)
--attach PATH	None	Add a file or folder outside the source to the disc root; never removed from its location; repeatable

These options require raw mode. See Raw data discs for the workflow and Planning raw discs for grouping, order and plans.

DAR options

Option	Default	Meaning
-c, --compression	zstd	zstd, lzma, lz4, gzip, bzip2, none
-l, --level	DAR's default (9)	Compression level forwarded to DAR; zstd 1–22, others 1–9; ignored with -c none
--base	None	Previous catalog slice file for an incremental
--pack-with	None	Unburned DAR ISO or individual disc folder to include in the new disc 1
--min-last-disc-fill	0 / off	Target fill percentage 0–100; defer newest eligible files using the preview estimate
--ratio	1.0	Estimated compressed output/input ratio
--sample	None	Sample directory to compress for a measured ratio

--ratio and --sample are mutually exclusive. These options require -m dar, except that raw mode tolerates -c none and the disabled deferral value 0. The old --raw flag is not supported. Existing DAR commands must specify -m dar, even if they already use DAR-specific options.

See Raw data discs, DAR archives and Incrementals and packing.

burn

bd-archive burn -i OUTPUT [options]

Option	Default	Meaning
-i, --input	Required	Create output directory containing disc/, discs/ or images/disc_*.iso
-D, --device	Auto-detect	Burner device
-S, --speed	Drive/tool maximum	Requested speed multiplier, such as 4
--write-timeout SECONDS	180	Minimum timeout per drive write command; integer 1–86400; longer existing timeouts are preserved
--buffer SIZE	512M	Ring buffer between source and drive: MiB, or a size with M/G suffix, 1M–64G, rounded up to a power of two; raise it for slow or unreliable source storage such as a NAS with hard disks
--start	1	First disc number to burn; must be within the disc set
--no-verify	Off	Skip post-burn verification
--no-close-tray	Off	Do not close the burner's tray after burning, so the disc can be moved to another drive for verification
--skip-fit-check	Off	Disable both too-small and oversized-media checks

burn has no --workdir. --no-close-tray is rejected together with --no-verify. See Burning for resume, cancellation and verifying in another drive.

verify

bd-archive verify [TARGET]

TARGET is a device, mounted/copied disc-root directory, or .iso file. Omit it to use the auto-detected drive. There is no -D option for this command.

Integrity results are 0 = OK, 1 = REPAIRABLE, 2 = BROKEN. Operational failures can also return 1; invalid syntax can return 2. Read Verification for scope and scripting caveats. This command does not repair data.

extract

bd-archive extract -o OUTPUT [-D DEVICE | -i PATH ...] [-w WORKDIR]

Option	Default	Meaning
-o, --output	Required	Empty directory or a previous restore of this chain
-D, --device	Auto-detect if no -i	Optical drive
-i, --input, --iso	None	Disc folders, ISO files or create output directories; alternative to -D
-w, --workdir	<output>/.bd-archive-work/	Temporary storage for all collected slices

Restores DAR only. No -n is needed: chain identity comes from the archive filenames. There is no file-selection or generation-selection flag; provide the relevant discs/images. Detected unrepaired corruption returns 1 and produces corrupted-files.txt when the extraction loop completes. See Restoring.