CLI reference

Every subcommand of `luksbox`, with examples.

The luksbox binary is a single CLI with subcommands for every vault operation. Run luksbox --help for the always-current list, or luksbox <subcommand> --help for per-subcommand detail.

Subcommand index

Command	Purpose
`create`	Create a new encrypted container with the first keyslot
`open`	Decrypt the header + slot, leave the vault open for follow-up commands
`mount`	Mount the vault as a real drive (FUSE on Linux/macOS, WinFsp on Windows)
`umount`	Unmount a previously-mounted vault
`enroll`	Add a new keyslot to an existing vault (passphrase, FIDO2, TPM 2.0, or any hybrid PQ variant)
`wizard`	Launch the interactive TUI - no flags to remember
`revoke`	Disable a keyslot without rotating the MVK
`rotate-mvk`	Generate a new MVK and re-wrap every active keyslot under it
`migrate-fido2-slot`	Migrate a pre-v0.3.0 FIDO2 keyslot to the cross-platform V4 convention
`put`	Add a file to the vault
`get`	Extract a file from the vault
`ls`	List directory contents inside the vault
`rm`	Remove a file from the vault
`info`	Show vault metadata (cipher, KDF, slot table)
`list-fido2-devices`	Enumerate plugged-in FIDO2 authenticators with their device paths
`kyber-init`	Generate a new `.kyber` seed file for hybrid-PQ vaults

Forensic and partial-recovery subcommands

These five live in their own section because they are post-incident tools, not day-to-day operations. See the forensics page for the workflow that ties them together.

Command	Purpose
`header-backup`	Save the 8 KiB header bytes to a separate file. Equivalent to `cryptsetup luksHeaderBackup`
`header-restore`	Restore the on-disk header from a previously saved backup (HMAC-verified by default)
`header-dump`	Decrypt the metadata blob and emit a JSON tree of every inode, chunk reference, and keyslot summary
`check`	Walk every used chunk, AEAD-decrypt it, report per-chunk status. Read-only
`extract`	Forensic best-effort extract: same as `get` but tolerates per-chunk AEAD failures (with explicit `--tolerate-errors` flag)

Common flags

Flag	Used by	Purpose
`--header <path>`	most	Detached header (default: header inline at start of `.lbx`)
`--cipher <aes\|chacha\|aes-siv>`	`create`	AEAD primitive (default: aes-siv = AES-256-GCM-SIV)
`--kdf <interactive\|sensitive>`	`create`, `enroll`	Argon2id preset
`--fido2-device <path>`	FIDO2 ops	Pin a specific authenticator (use `list-fido2-devices` to find paths)
`--kind <slot-kind>`	`create`, `enroll`	Pick the keyslot kind: `passphrase` / `fido2` / `tpm2` / `tpm2-pin` / `tpm2-fido2` / `hybrid-pq` / `hybrid-pq-fido2` / `hybrid-pq-tpm2` / `hybrid-pq-tpm2-fido2` (and the `1024` variants of each hybrid)
`--pq-hybrid <kyber-path>`	hybrid-PQ ops	Path to the `.kyber` seed file
`--sync`	`mount`, `deniable-mount`	Eager flush: every metadata-mutating op is durable on return. Default is deferred (a 30 s background timer drives flushes), which keeps `rm` / `cp -r` fast on vaults with thousands of files. See `mount` -> Flush policy.

Environment variables

Variable	Purpose
`LUKSBOX_PASSPHRASE`	Read existing passphrase from env (avoids tty prompt; useful for scripts)
`LUKSBOX_NEW_PASSPHRASE`	Read a new passphrase (e.g. for `create` or `enroll --passphrase`)
`LUKSBOX_FIDO2_PIN`	Provide the FIDO2 PIN non-interactively
`LUKSBOX_TEST_FAST_KDF`	Override Argon2id to weak-test parameters - debug builds only, compiled out of release binaries
`LUKSBOX_NO_FOLLOW_SYMLINKS`	Refuse to open vaults whose path is a symlink (paranoid mode)

For full per-subcommand help: luksbox <subcommand> --help.