vault

fialr vault <action> [path] [options]

Create, open, close, and manage encrypted vaults. Vaults are general-purpose encrypted containers for any file. Tier 1 files are recommended for vault storage but not required.

fialr ships two password-only backends, both native and neither requiring a third-party kernel extension:

APFS (macOS default) — an Apple-native encrypted sparse bundle.
age (Linux default, also works on macOS) — modern per-file encryption.

Actions

Action	Description	Backends
`create`	Create a new encrypted vault	apfs, age
`open`	Mount a vault (makes contents accessible)	apfs
`close`	Dismount a vault	apfs
`status`	Show vault state (default)	apfs, age
`archive`	Archive files into the vault with integrity verification	apfs, age
`rehydrate`	Restore files from the vault	apfs, age
`list`	List files currently stored in the vault	apfs, age

Arguments

Argument	Description
`path`	Path to the vault (container file or directory)

Options

Option	Description
`--backend BACKEND`	Encryption backend: `apfs` or `age`. Default: `apfs` on macOS, `age` on Linux.
`--execute`	Archive/rehydrate for real. Without it, `archive` and `rehydrate` run as a dry-run preview (no mount, no encryption, no writes).
`--size SIZE`	Vault size, e.g. `100M`, `1G`. Used by APFS. Ignored by age.
`--db PATH`	Path to fialr SQLite database (for operation logging)
`--vault PATH`	Path to the vault (for `archive`/`rehydrate`)
`--dest PATH`	Destination directory (for `rehydrate`)

Backends

APFS (macOS default)

Native encrypted sparse bundle via hdiutil. Zero install, no third-party kernel extension, no change to your Mac’s security posture. Mountable volume with AES-256 encryption. iCloud-compatible.

age (Linux default, cross-platform)

Per-file encryption via the age CLI. No mount semantics — the vault is a directory of individually encrypted files. Files are decrypted on demand during archive and rehydrate. One-command install (brew install age or apt install age). Because fialr addresses files by content hash and decrypts on demand, an age vault is portable to any OS with age and the passphrase — no mountable container required.

The passphrase is delivered to age through a pseudo-terminal, so archive and rehydrate run non-interactively (no TTY required) without ever placing the passphrase on the command line.

What it does

Create

Creates an encrypted vault at the specified path. Prompts for a password interactively — passwords are never accepted as CLI arguments. APFS creates a .sparsebundle; age creates a directory.

Open / Close (APFS)

open mounts the vault to a temporary directory and returns the mount point; close dismounts it. These do not apply to age vaults (age directories are always accessible; individual files are decrypted during archive/rehydrate).

Status

Reports the vault backend, file count, and total size. For APFS, also reports whether the vault is currently mounted.

Rehydrate

rehydrate restores files from the vault to a destination (the current directory by default, or --dest <dir>). File integrity is verified via BLAKE3 hash. The vault entry is removed from the vault_entries table and a rehydrate operation is logged.

Dry-run is the default here too: without --execute, rehydrate reports which hashes would be restored (for age, it confirms each {hash}.age is present; for APFS it reports each hash as “would attempt”, since the volume is not mounted during a preview) and writes nothing. Pass --execute to restore.

List

list shows all files currently archived in the vault. For APFS, this includes original paths and archive timestamps. For age, the directory listing shows the content-hash artifact names ({hash}.age) only — the original filename is encrypted inside each blob and is recovered on rehydrate, not on list.

Security

Passwords are prompted interactively and delivered to the backend via stdin (APFS) or a pseudo-terminal (age) — never visible in process listings or on the command line
Mount points use 0700 permissions and are cleaned up on close (APFS)
Archive and rehydrate operations verify file integrity via BLAKE3 hash before and after
All vault containers use standard formats — no proprietary format, no third-party kernel extension

Output

APFS vault (macOS default):

vault create ~/secure-vault --backend apfs --size 1G

  VAULT     created
────────────────────────────────────────────────────────
   created  ~/secure-vault.sparsebundle
   backend  apfs

vault status ~/secure-vault

  VAULT     mounted
────────────────────────────────────────────────────────
      path  ~/secure-vault.sparsebundle
     mount  /tmp/fialr-vault-a1b2c3
   backend  apfs
     files  14
      size  23.4 MB

Examples

Platform defaults

# macOS — APFS encrypted sparse bundle (default)
fialr vault create ~/secure-vault --size 1G

# Linux — age per-file encryption (default, no --size needed)
fialr vault create ~/secure-vault

Common operations (both backends)

# Preview archiving a file (dry-run, the default — writes nothing)
fialr vault archive ~/secure-vault ~/Documents/tax-return-2024.pdf

# Archive it for real
fialr vault archive ~/secure-vault ~/Documents/tax-return-2024.pdf --execute

# Archive multiple files
fialr vault archive ~/secure-vault ~/Documents/passport-scan.pdf ~/Documents/ssn-card.pdf --execute

# List vault contents
fialr vault list ~/secure-vault

# Preview rehydrating a file by content hash (dry-run)
fialr vault rehydrate ~/secure-vault a1b2c3d4...

# Rehydrate it for real, to a specific destination
fialr vault rehydrate ~/secure-vault a1b2c3d4... --dest ~/restored/ --execute

# Check vault status
fialr vault status ~/secure-vault

APFS (mountable vault)

# Open (mount) a vault
fialr vault open ~/secure-vault

# Close (dismount) when done
fialr vault close ~/secure-vault