KeyRex is a secure, lightweight key–value vault for managing sensitive information locally written in Rust. It combines robust encryption, clear operational feedback, and a polished command-line interface to make secret management simple yet reliable.
- Secure Local Storage — Secrets are stored locally in
~/.keyrex/vault.dat, never leaving your system. - AES-256 Encryption — Optional password-protected encryption with industry-standard algorithms.
- Elegant CLI — A clean, color-coded interface designed for usability and clarity.
- Search & Filter — Quickly locate entries with pattern-based search.
- Vault Analytics — Track creation, update, and access timestamps.
- Safety Mechanisms — Built-in confirmation for destructive operations and duplicate prevention.
- High Performance — Written in Rust for maximum speed and minimal overhead.
cargo install --path . --bin keyrexThis installs an executable named keyrex into your Cargo binary directory.
Ensure this directory is included in your system PATH.
Download the latest release for your platform from the Releases page. <TODO: add link>
keyrex completions install| Command | Description |
|---|---|
keyrex add <key> <value> |
Add a new entry |
keyrex get <key> |
Retrieve a stored value |
keyrex update <key> <value> |
Update an existing entry |
keyrex remove <key> |
Remove an entry (with confirmation) |
Additional flags:
--yes/-y: Skip confirmation--copy/-c: Copy value to clipboard (secure - value won't be printed to stdout)
keyrex list # Show all keys
keyrex list --values # Show keys and values
keyrex list --sort # Sort alphabetically
keyrex search <pattern> # Search entries
keyrex search <pattern> --values # Include values in resultsEach entry can have multiple tags:
keyrex tag mistral ai # Add a tag
keyrex tag mistral europe # Keep ai and add europe
keyrex tag mistral europe --replace # Replace all tags with europe
keyrex tag mistral ai --remove # Detach ai from mistral
keyrex tag mistral --remove # Detach all tags from mistral
keyrex tag --list # List all tags alphabetically
keyrex tag ai # List entry names tagged ai
keyrex tag ai --include-keys # Include stored secret values
keyrex tag rename aii ai # Rename on every entry
keyrex tag remove ai # Detach ai everywhere; keep entriesTags are case-sensitive and duplicates are ignored. Quote tags containing spaces,
for example keyrex tag mistral "european ai". Renaming to an existing tag merges
their memberships. Tags disappear from the list when no entries use them; updating
a secret preserves its tags. Existing plaintext and encrypted vaults work without
a migration command.
rename and remove are tag subcommands. To use either as an entry or tag name,
put options first and use --, for example keyrex tag -- rename ai or
keyrex tag --include-keys -- remove.
keyrex info # Display vault metadata
keyrex clear # Remove all entries (confirmation required)keyrex vault export # Encrypted backup in the current directory
keyrex vault export ./backup.json # Choose an output file
keyrex vault export ./backup.json --plaintext # Readable JSON for interoperability
keyrex vault import ./backup.json # Restore into a missing vault
keyrex vault import ./backup.json --replace # Replace an existing or damaged vault
keyrex vault import ./backup.json --merge # Combine entries; duplicate keys fail
keyrex vault import ./backup.json --merge --on-conflict skip
keyrex vault import ./backup.json --merge --on-conflict overwriteExport prompts for a separate backup password and defaults to
keyrex-vault-<UTC timestamp>.json. Exporting an encrypted vault first requires
its current password. Existing backup files are never overwritten. --plaintext
exports readable secret values; --plain is an alias.
Import uses the vault location selected by --config or the default configuration.
A full restore preserves the backup's entries, tags, and vault timestamps. An
encrypted backup becomes an encrypted vault using the backup password; a
plaintext backup becomes a plaintext vault. Restoring with --replace works even
when the existing vault is damaged, without requiring its old password.
Merging into an existing vault keeps its password, encryption setting, creation
time, and access time. A changed merge updates the modification time. Duplicate
keys fail before any changes unless --on-conflict skip keeps the local entry or
--on-conflict overwrite replaces its value and complete tag set. A merge into a
missing vault behaves like a full restore. Merges that change nothing leave the
vault file untouched.
Import asks for confirmation before it would store secrets unencrypted that are
encrypted today: restoring a plaintext backup over an encrypted vault, or merging
an encrypted backup into a plaintext vault. --yes skips the question. Declining,
or running without a terminal to answer, exits with an error and leaves the vault
unchanged.
Before modifying an existing vault, import saves its exact contents beside it as
<vault filename>.pre-import-<UTC timestamp>.bak and prints that path. These are
native vault recovery copies, so restore one by copying it back to the configured
vault location while KeyRex is closed. A recovery copy keeps the old vault's
protection, so delete it once you no longer need it; keyrex encrypt lists any
unencrypted copies still beside the vault. Import rejects symlinked backup files,
invalid entries, duplicate keys or unknown fields inside a backup, and unsupported
formats. Backup and recovery files use owner-only permissions on Unix.
If the configured vault path is a symlink, KeyRex reads and updates the file it points to and leaves the link in place.
Backups use the versioned logical backup schema. Machine-specific configuration and vault paths are not included.
Enable or disable encryption:
keyrex encrypt # Prompts for password setup
keyrex decrypt # Disables encryption- Encrypted vaults automatically prompt for a password when accessed.
- The password is cached for the session to avoid repeated prompts.
- Encryption uses AES-256-GCM with PBKDF2-HMAC-SHA256 key derivation (600,000 iterations).
- Incorrect passwords trigger a clear and non-ambiguous error message.
# Add a secret
$ keyrex add github_token ghp_xxxxxxxxxxxx
✓ Added entry 'github_token'
# List keys alphabetically
$ keyrex list --sort
Vault entries (3):
api_key
database_password
github_token
# Search for a specific key
$ keyrex search github --values
Found 1 matching entries:
github_token: ghp_xxxxxxxxxxxx
# Retrieve a value securely (copy to clipboard without printing)
$ keyrex get github_token --copy
✓ Value copied to clipboard
# View vault information
$ keyrex info
Vault Information
Location: /home/alex/.keyrex/vault.dat
Entries: 3
Created: 2025-10-30 22:02:34 UTC
Last Updated: 2025-10-30 22:11:40 UTC
Last Accessed: 2025-10-30 22:11:40 UTC- Duplicate Protection — Prevents accidental overwrites.
- Destructive Action Confirmation — Prompts before executing
removeorclear. - Comprehensive Error Handling — Human-readable error output for all failure states.
- Exit Codes — Standardized return codes for scripting (0 = success, 1 = error).
| Command | Description | Options |
|---|---|---|
add <key> <value> |
Add a new entry | — |
get <key> |
Retrieve an entry | --copy, -c: Copy to clipboard |
update <key> <value> |
Update an entry | — |
remove <key> |
Delete an entry | --yes, -y: Skip confirmation |
list |
List entries | --values, -v: Include values--sort, -s: Sort alphabetically |
search <pattern> |
Search keys or values | --values, -v: Include values |
tag [<name>] [<tag>] |
Tag entries or query tags | --replace, --remove, --list, --include-keys |
tag rename <old> <new> |
Rename a tag on every entry | — |
tag remove <tag> |
Remove a tag, keeping entries | — |
info |
Show vault metadata | — |
clear |
Clear all entries | --yes, -y: Skip confirmation |
vault export [path] |
Export an encrypted logical backup | --plaintext: Export readable JSON |
vault import <path> |
Restore or merge a backup | --replace, --merge, --on-conflict error|skip|overwrite, --yes |
encrypt |
Enable AES-256 encryption | — |
decrypt |
Disable encryption | — |
src/
├── main.rs # Application entry point with structured logging
├── cli.rs # CLI argument definitions
├── vault.rs # Data model and persistence layer
├── backup.rs # Logical backup format, restore, and merge
├── storage.rs # Secure file staging and replacement
├── crypto.rs # AES-256-GCM encryption implementation
├── config.rs # Multi-platform configuration management
├── security.rs # Security validation utilities
├── session.rs # Session password management
├── output.rs # Terminal output utilities
├── logging.rs # Structured logging with tracing
├── completions.rs # Shell completion generation
└── commands/ # Command handlers
├── mod.rs # Command router
├── crud.rs # Add, Get, Update, Remove handlers
├── query.rs # List, Search, Info, Keys handlers
├── security.rs # Encrypt, Decrypt handlers
├── vault.rs # Vault export/import handlers
└── meta.rs # Clear handler
For more details, see CLAUDE.md.
- Storage Format: JSON (or base64-encoded encrypted data) via
serde. - Default Location:
~/.keyrex/vault.dat(configurable via config file) - Configuration: Multi-platform config file support with environment variable expansion
- Encryption: AES-256-GCM with PBKDF2-HMAC-SHA256 key derivation (600k iterations).
- Clipboard: Cross-platform clipboard support via arboard (Linux X11/Wayland, macOS, Windows).
- Timestamps: Tracks creation, modification, and last access (UTC).
getrecords access times in<vault stem>.accessbeside the vault, so reads never rewrite it. - CLI Framework: Clap for argument parsing.
- Color Output: Colored for consistent terminal styling.
- Logging: Structured logging with tracing (configurable via
RUST_LOG). - Security: File permission validation, atomic file writes, secure memory handling.
- Architecture: Modular, maintainable, and fully separated by concern.
- Testing: Comprehensive test isolation - all tests use temporary directories.
- Random password generation
- Multi-vault management
- Automatic backups and sync capabilities
- Biometric authentication
- GPG integration for hybrid encryption
- Cloud sync support (e.g., Dropbox, Google Drive)
- Sync Manager integration (e.g., Bitwarden, 1Password)
- Cross-Platform Testing — Full CI test coverage for macOS and Windows (currently limited to Ubuntu to minimize CI usage)
- Windows Support — Complete Windows platform support with comprehensive testing
- macOS Testing — Expanded macOS test coverage in CI pipeline
Contributions, ideas, and feedback are always welcome! If you’d like to improve KeyRex, fix a bug, or suggest a new feature, please see the full guidelines here:
The following crates power KeyRex's core functionality:
Security & Encryption:
aes-gcm— AES-256-GCM authenticated encryption.pbkdf2— Password-based key derivation using HMAC-SHA256.sha2— Secure hash functions used in PBKDF2.zeroize— Secure memory zeroization to protect key material.rand— Cryptographically secure random number generation.rpassword— Safe password input for the CLI.
CLI & Output:
clap— Command-line argument parsing and help generation.clap_complete— Dynamic shell completions forbash,fish,zsh, etc.colored— Rich, colorized terminal output.arboard— Cross-platform clipboard support.
Logging & Observability:
tracing— Structured logging framework.tracing-subscriber— Tracing output formatting and filtering.
Configuration & Data:
serde&serde_json— Data serialization and vault persistence.toml— TOML configuration file parsing.shellexpand— Environment variable expansion in config paths.chrono— Timestamp management withserdeintegration.dirs— Cross-platform handling of user directories.base64— Encoding for encrypted vault entries.fslock— File locking for concurrent access safety.thiserror— Custom error type definitions.