Commands

Path and symlink policy

File-touching commands share a default-deny policy. There is no --follow-symlinks flag and links are never skipped silently.

• Any symlink, Windows junction, or other detected reparse point in a supplied input, output leaf, or existing parent component aborts the operation and names the rejected path.
• Nested links inside a tree are rejected only by commands that recurse (directory encrypt/decrypt, tree secure-delete, schedule directory runs, and watch events).
• Checks run before --dry-run, password prompts, reads, writes, overwrite checks, or deletes.
• Directory outputs are joined with lexical containment (filepath.Clean + filepath.Rel, never string-prefix matching). Absolute, .., non-local, reserved-device (NUL/CON/COM1), rooted-backslash, and volume-qualified relatives are rejected.
• SYMLINK_DISALLOWED: use a regular file or directory path. Symlinks are not followed.
• PATH_ESCAPE: use a relative path that stays inside the selected output directory.
• Watch and schedule always print those two policy errors. Ordinary watch permission/I/O errors still require --verbose.
• This is not race-proof against a privileged local attacker replacing a path component between validation and open. Descriptor-relative OS APIs are out of scope.

Machine-readable output

Operational commands inherit --json, which emits stable schema-version-1 records for scripts and SOAR workflows. In this mode stdout contains JSON only, stderr stays empty, prompts and progress bars are disabled, and failures use a nonzero exit code with a structured error.

• encrypt, decrypt, secure-delete, and rotate-key emit exactly one result or error object.
• watch and schedule encrypt emit newline-delimited JSON (NDJSON) lifecycle, file, completion, and failure events.
• Consumers should ignore unknown fields. A breaking field or meaning change requires a new schema version.
• Help, version, completion, and config are not part of the version-1 operational schema.

# One bounded result
nokvault encrypt evidence.img --keyfile ./key --no-prompt --json

# Filter a long-running NDJSON stream
nokvault watch ./incoming --auto-encrypt --keyfile ./key --no-prompt --json \
  | jq -c 'select(.event == "encryption.completed")'

encrypt <path>

Encrypt a file or directory using AES-256-GCM. Supports files and recursive directory encryption. Nested input or output links abort the whole tree; no ciphertext is written for the rejected path.

Options

• --output, -o: Specify output file path (default: <path>.nokv)
• --keyfile, -k: Path to keyfile for encryption (mode 0600 required on Unix; symlinks refused)
• --password, -p: Removed - refused at runtime (use keyfile, NOKVAULT_PASSWORD, or prompt)
• --no-prompt: Don't prompt for password
• --compress: Compress before encryption
• --dry-run: Show what would be encrypted without actually encrypting
• --force, -f: Overwrite existing output path
• --verbose, -v: Verbose output

Race-safe writes without --force require hard-link support on the destination filesystem. FAT/exFAT and some network filesystems may reject the operation.

Examples

# Encrypt a file
nokvault encrypt document.txt

# Encrypt with compression
nokvault encrypt large-file.bin --compress

# Use keyfile
nokvault encrypt file.txt --keyfile ~/.keys/master.key

decrypt <path>

Decrypt a nokvault encrypted file or directory. Automatically detects encrypted files and restores original structure. A symlink or reparse output parent is rejected before credentials are read. Policy errors stay typed even without --strict.

Options

• --output, -o: Specify output file path
• --keyfile, -k: Path to keyfile for decryption (mode 0600 required on Unix; symlinks refused)
• --password, -p: Removed - refused at runtime (use keyfile, NOKVAULT_PASSWORD, or prompt)
• --no-prompt: Don't prompt for password
• --preserve-mode: Restore original file modes (default clamps to ≤0600 files / ≤0700 dirs)
• --force, -f: Overwrite existing output path
• --strict: Abort directory decrypt on the first failure (leave already-written files; default continues and reports partial results)
• --dry-run: Show what would be decrypted
• --verbose, -v: Verbose output

Race-safe writes without --force require hard-link support on the destination filesystem. FAT/exFAT and some network filesystems may reject the operation.

Examples

# Decrypt a file
nokvault decrypt document.txt.nokv

# Decrypt with keyfile
nokvault decrypt file.nokv --keyfile ~/.keys/master.key

# Decrypt directory
nokvault decrypt ./encrypted-documents

watch <path>

Watch a directory for file changes and optionally auto-encrypt files when they are created or modified. A symlink watch root is refused at startup. Symlink events are rejected and never encrypted; delayed encrypt re-checks the path before writing.

Options

• --auto-encrypt: Automatically encrypt files on change
• --keyfile, -k: Path to keyfile
• --delay: Delay before processing changes (default: 1s)
• --exclude: Exclude patterns
• --recursive: Watch subdirectories recursively
• --verbose, -v: Verbose output

Examples

# Watch directory with auto-encryption
nokvault watch ./documents --auto-encrypt --keyfile ~/.keys/master.key

# Watch with delay and exclusions
nokvault watch ./sensitive --auto-encrypt \
  --keyfile ~/.keys/master.key \
  --delay 5s \
  --exclude "*.tmp"

schedule encrypt <path>

Schedule periodic encryption operations. Useful for automated backups and regular encryption tasks. The configured path and generated outputs are validated at startup and again on every tick before mutation.

Options

• --interval: Time interval between operations (e.g., 1h, 30m, 1d)
• --keyfile, -k: Path to keyfile
• --compress: Compress before encryption
• --verbose, -v: Verbose output

Examples

# Encrypt every hour
nokvault schedule encrypt ./backups --interval 1h --keyfile ~/.keys/backup.key

# Encrypt daily
nokvault schedule encrypt ./documents --interval 24h

rotate-key <path>

Re-key an encrypted file by decrypting with the old credential and re-encrypting with a new one (new salt and ciphertext). Prefer keyfiles over prompts for automation. Symlink or reparse inputs are rejected before passwords are requested.

Options

• --old-keyfile: Path to old keyfile
• --new-keyfile: Path to new keyfile
• --old-password / --new-password: Removed - refused at runtime
• --no-prompt: Don't prompt for passwords
• --verbose, -v: Verbose output

Examples

# Rotate key for a file
nokvault rotate-key file.nokv

# Rotate with specific keyfiles
nokvault rotate-key file.nokv \
  --old-keyfile ~/.keys/old.key \
  --new-keyfile ~/.keys/new.key

secure-delete <path>

Best-effort overwrite and deletion for traditional spinning disks. SSD wear leveling, snapshots, and copy-on-write filesystems may retain prior data; this is not a guaranteed forensic wipe. Symlink or reparse paths are refused; the link and its target are left untouched.

Options

• --passes, -p: Number of overwrite passes (default: 3)
• --yes, -y: Confirm deletion without prompting (required when stdin is not a TTY)
• --dry-run: List paths that would be deleted without deleting
• --verbose, -v: Verbose output

Examples

# Preview what would be deleted
nokvault secure-delete sensitive-file.txt --dry-run

# Secure delete (scripts / CI)
nokvault secure-delete sensitive-file.txt --yes

# Secure delete with custom passes
nokvault secure-delete sensitive-file.txt --yes --passes 7

config

Initialize or inspect the Argon2id settings used for new encryptions.

Subcommands

• --init: Initialize default configuration
• --show: Show current configuration
• --get <key>: Read memory_cost, time_cost, or parallelism

Examples

# Initialize configuration
nokvault config --init

# View current configuration
nokvault config --show

# Get a specific value
nokvault config --get memory_cost