Usage

koava encrypt <MODEL_PATH> [OPTIONS]

Aliases:

koava enc <MODEL_PATH> [OPTIONS]

For help:

koava encrypt -h

Description

The encrypt command:

converts standard safetensors files to cryptotensors format (i.e, KoalaVault’s encrypted format). See CryptoTensors File Format for detailed information about the encrypted format.
inserts compliance block into README.md and adds LICENSE.KOALAVAULT to clearly state the model is encrypted and license-gated via KoalaVault. See Hugging Face Compliance for more details.

Important: After encryption, you must create a model on Hugging Face, upload the complete encrypted model files, and then update the KoalaVault model page with the Hugging Face URL. You can use the koava push command to do this complete workflow in one step.

Currently, KoalaVault only supports safetensors format files.

Prerequisites

Before running encrypt, you must ensure that a model has been created on KoalaVault (either manually or using koava create). This is required because KoalaVault generates model-specific encryption and user-specific signing keys for each publisher and model only after a model is created. The encrypt command needs to retrieve these keys to encrypt and sign your model files.

Backup Process

When encrypting in-place (without specifying --output), the encrypt command automatically creates a backup of your original files before encryption. The backup is stored in a .backup directory within your model folder, ensuring your original files are preserved in case you need to restore them later.

README & License Handling

This section explains how encrypt updates documentation to ensure compliance while preserving your originals.

README
- Duplicate-safe insertion: the tool uses an invisible marker to ensure the compliance block is inserted at most once.
- In-place (default): inserts a short compliance block into <MODEL_PATH>/README.md (after the first title). If no README exists, a minimal README is created.
- With --output: the source README is never modified. A README.md is written to the output directory: if a source README exists, the block is inserted into that content; otherwise, a minimal README is created in the output.
- Restore behavior: if no README backup is present but the current README contains the marker, koava restore removes the tool-inserted README (in in-place scenarios).
License
- The original LICENSE is never modified.
- A parallel LICENSE.KOALAVAULT is created alongside the encrypted model files to clarify redistribution and execution rights for encrypted artifacts.
- koava restore removes LICENSE.KOALAVAULT.

Examples

Basic Encryption Workflow

# 1. Preview what will be encrypted
koava encrypt ./my-model --dry-run

# 2. Encrypt the model
koava encrypt ./my-model -n "my-awesome-model"

# 3. Verify encryption was successful
ls ./my-model/

Custom Output Workflow

# 1. Encrypt to separate directory
koava encrypt ./my-model --output ./encrypted-models --name "my-llm"

# 2. Verify output
ls ./encrypted-models/

Advanced

Arguments

MODEL_PATH

Directory containing safetensors files to encrypt (required).

Options

—name, -n

Model name for encryption key retrieval, must match the model name on KoalaVault. Default resolution order when not provided:

If --output/-o is specified: use the basename of the output directory
Otherwise: use the basename of <MODEL_PATH>

# Explicitly set name
koava encrypt ./my-model --name "llama-7b-chat"

# Defaults to output directory basename (my-aws-model)
koava encrypt ./qwen3-0.6b --output ./my-aws-model

# Defaults to model path basename (my-model)
koava encrypt ./my-model

—output, -o

Output directory for encrypted files (defaults to in-place encryption). When specified, the encrypted model will be saved in the specified directory.

koava encrypt ./my-model --output ./encrypted-models

—no-backup

Skip automatic backup (only works when --output is not specified, i.e. when encrypting in-place). When not specified, a backup directory .backup will be created in the same directory as the model. The original model files will be copied to the backup directory before encryption.

koava encrypt ./my-model --no-backup

Warning: Skipping backup is not recommended. If encryption fails, you may lose your original files.

—files

Only encrypt specific model files (comma-separated, only includes model files, not configuration files). When not specified, all model files will be encrypted.

koava encrypt ./my-model --files "model1.safetensors,model2.safetensors"

—exclude

Exclude specific model files from encryption (comma-separated, only includes model files, not configuration files). When not specified, all model files will be encrypted.

koava encrypt ./my-model --exclude "model1.safetensors,model2.safetensors"

—dry-run

Preview what would be encrypted without making changes.

koava encrypt ./my-model --dry-run

—force

Force encryption even if backup directory exists. When a backup directory already exists with unencrypted files:

Without --force: Encrypts from the existing backup files
With --force: Overwrites the backup directory with current files, then encrypts

This flag only affects in-place encryption when a backup directory already exists.

koava encrypt ./my-model --force

Restore Original Files

To restore original files:

koava restore ./my-model

See koava restore for details.

koava restore - Restore original files from backup
koava upload - Upload encrypted model to KoalaVault
koava push - Complete workflow (create + encrypt + upload)

Getting Started

Koava CLI

vLLM Deployment

Security & Policies

Cryptocurrency

koava encrypt

Usage

Description

Prerequisites

Backup Process

README & License Handling

Examples

Basic Encryption Workflow

Custom Output Workflow

Advanced

Arguments

MODEL_PATH

Options

—name, -n

—output, -o

—no-backup

—files

—exclude

—dry-run

—force

Restore Original Files

See also

​Usage

​Description

​Prerequisites

​Backup Process

​README & License Handling

​Examples

​Basic Encryption Workflow

​Custom Output Workflow

​Advanced

​Arguments

​MODEL_PATH

​Options

​—name, -n

​—output, -o

​—no-backup

​—files

​—exclude

​—dry-run

​—force

​Restore Original Files

​Related Commands

​See also

Usage

Description

Prerequisites

Backup Process

README & License Handling

Examples

Basic Encryption Workflow

Custom Output Workflow

Advanced

Arguments

MODEL_PATH

Options

—name, -n

—output, -o

—no-backup

—files

—exclude

—dry-run

—force

Restore Original Files

Related Commands

See also