Basic Usage

Encrypt a file

The simplest way to encrypt a file is the encrypt command:

nokvault encrypt document.txt

This creates document.txt.nokv and prompts for a password. The original file remains unchanged unless you pass --delete-original.

Decrypt a file

Decrypt with the decrypt command:

nokvault decrypt document.txt.nokv

NokVault detects the original filename and restores it. You are prompted for the password used during encryption.

Use a keyfile

Keyfiles avoid typing a password for each operation. Create a keyfile and pass it to encrypt and decrypt:

# Generate a random keyfile (using openssl or similar)
openssl rand -out ~/.keys/master.key 32

# Encrypt with keyfile
nokvault encrypt document.txt --keyfile ~/.keys/master.key

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

Important: Keep keyfiles mode 0600. NokVault refuses group/world-readable keyfiles on Unix and rejects symlink keyfiles. Back them up securely - without the keyfile, encrypted data cannot be recovered.

Using environment variables

For automation, you can supply a password through the environment instead of an interactive prompt. Prefer keyfiles when possible: NOKVAULT_PASSWORD is still visible to other processes on the same machine. Passwords on the command line (--password / -p) are refused.

# Set password as environment variable
export NOKVAULT_PASSWORD="your-secure-password"

# Encrypt without prompt
nokvault encrypt document.txt --no-prompt

# Unset after use
unset NOKVAULT_PASSWORD

Encrypting directories

NokVault can encrypt entire directories recursively:

# Encrypt a directory
nokvault encrypt ./documents

# The directory structure is preserved
# Each file is encrypted individually

Each file is encrypted separately, so you can decrypt individual files later. A nested symlink, junction, or other reparse point aborts the whole operation; no ciphertext is written for that link.

Specifying output location

By default, encrypted files are created beside the input with a .nokv extension. You can choose a custom output:

# Encrypt to specific location
nokvault encrypt document.txt --output ./encrypted/secure.nokv

# Decrypt to specific location
nokvault decrypt document.nokv --output ./decrypted/restored.txt

Dry run

Preview an encryption with --dry-run. Path policy still runs first: a symlink or escaping output is rejected before the preview and before any password prompt.

# See what would be encrypted
nokvault encrypt ./documents --dry-run

# This shows which files would be processed without actually encrypting