readme.templ.md

vlt - A secure command-line tool for managing secrets in your terminal.

vlt provides secure, local management of your sensitive information, ensuring your secrets remain encrypted at rest and are only briefly decrypted in memory when accessed.

Table of Contents

• vlt - A secure command-line tool for managing secrets in your terminal.
  • Supported Platforms
  • Installation
    • Option 1: Install via curl
    • Option 2: Download a release
      • Optional install script
    • Option 3: Build from source (requires Go 1.24 or newer)
  • Design Overview
    • vlt - cli client
    • vltd - session manager daemon
  • Crypto/Security
  • Usage
  • Configuration file
  • Examples
    • Tips and Tricks
      • Interactive Secret Selection
      • Sync to a Git Repository

Supported Platforms

• OS: Linux
  • Tested on (amd64):
    • Debian 12
    • Debian 13
    • Fedora 42
    • Fedora 43
• Arch: Prebuilt binaries are available for amd64, arm64, and 386.

Installation

Option 1: Install via curl

curl -sSL https://raw.githubusercontent.com/ladzaretti/vlt-cli/main/install.sh | bash

This script:

• Detects your OS and architecture
• Downloads the latest release from GitHub
• Extracts the archive
• Runs the included install.sh to copy binaries and optionally install the systemd service

Option 2: Download a release

Visit the Releases page for a list of available downloads.

Optional install script

After downloading and extracting an archive, the install.sh script can be used to:

• Copy the vlt and vltd binaries to /usr/local/bin
• Install and enable the vltd systemd user service for managing vault sessions

Option 3: Build from source (requires Go 1.24 or newer)

# Clone and build
git clone https://github.com/ladzaretti/vlt-cli.git
cd vlt-cli
make build-dist

# Optional: run the install script
./dist/install.sh

This packs the vlt and vltd binaries in ./dist/.

Warning

Installation via go install is not supported due to a patched vendored dependency.

Design Overview

vlt - cli client

The vlt cli manages secrets stored in a vault system composed of two layers:

• vault_container.sqlite is the outer SQLite database. It stores crypto metadata (auth PHC, KDF PHC, nonce, checksum) and a single encrypted, serialized SQLite instance as a binary blob.
• vault.sqlite is a serialized and encrypted inner SQLite database that contains the actual user data (secret names, labels, ciphertexts).
  • The decrypted vault.sqlite is held in the vlt process memory only and is never written to disk.

vltd - session manager daemon

The vltd daemon manages derived encryption keys and exposes a Unix socket that vlt uses to obtain them. The socket is created at /run/user/<uid>/vlt.sock with 0600 permissions and only accepts connections from the same UID. Only vlt accesses the database files directly.

graph LR
    subgraph VltFile[".vlt file"]
      subgraph VaultContainer["vault_container.sqlite database"]
          EncryptedVault["vault.sqlite (encrypted serialized database blob)"]
        end
    end

    vlt["vlt (client)"]
    vltd["vltd (daemon)"]
    socket["Unix socket"]

    vlt -->|read/write| VaultContainer
    vlt -->|decrypt + access| EncryptedVault
    vlt -->|request/store session keys| socket --> vltd

Loading

Crypto/Security

• Key Derivation & Auth: Uses argon2id to derive keys from the master password and verify authentication.

• Encryption:

  • Secrets are encrypted with AES-256-GCM, using unique nonces for each encrypted value.
  • The backing SQLite database is encrypted at rest and only decrypted into memory after authentication.
  • The outer container stores crypto metadata in plaintext (PHC strings, nonce, checksum) plus the encrypted vault blob.

• Session Keys: Stored in the daemon's memory only for the configured session duration and cleared on logout/expiry.

• Memory-Safety: Secrets are stored in memory only, with best effort zeroization of buffers on session end and vault close.

Usage

$ vlt --help
{{USAGE}}

Configuration file

The optional configuration file can be generated using vlt config generate command:

{{CONFIG}}

Examples

These are minimal examples to get you started.
For detailed usage and more examples, run each subcommand with --help.

# Create a new vault
vlt create

# Import secrets from a file (auto-detects format if compatible, e.g., Firefox or Chromium)
vlt import passwords.csv

# Save a secret interactively
vlt save

# Remove a secret by its name or label
vlt remove foo

# Find secrets with names or labels containing "foo"
vlt find "*foo*"

# List all secrets in the vault
vlt find

# Show a secret by name or label and copy its value to the clipboard
vlt show foo --copy-clipboard

# Show a secret by ID and write its value to a file
vlt show --id 42 --output secret.file

# Use a glob pattern and label filter, print to stdout (unsafe)
vlt show "*foo*" --label "*bar*" --stdout

# Rename a secret by ID
vlt update --id 42 --set-name foo

# Update secret value with a random generated secret
vlt update secret foo --generate

# Rotate the master password
vlt rotate

Tips and Tricks

Interactive Secret Selection

# Use fzf to select a secret interactively and copy its value to the clipboard
vlt login
vlt ls -P | fzf --header-lines=1 | awk '{print $1}' | xargs -r vlt show -c --id

Sync to a Git Repository

Use the post_login_cmd and post_write_cmd hooks to sync the vault with a bare Git repository.

Example setup using fish shell:

# Bare git repository alias
$ cat .config/fish/alias.fish | grep vault
alias vault_git='/usr/bin/git --git-dir="$HOME/.vltd/" --work-tree="$HOME"'

# Vault hooks configuration
$ cat ~/.vlt.toml | grep -A3 hooks
[hooks]
post_login_cmd=['fish','-c','vault_git pull']
post_write_cmd=['fish','-c',"vault_git add -u && vault_git commit -m \"$(date +'%Y-%m-%d %H:%M:%S')\" && vault_git push"]