OniLock - Secure Password Manager CLI

OniLock is a command-line password manager that allows you to securely store, retrieve, and manage your passwords with ease. Designed for simplicity and security, OniLock offers encryption and clipboard integration to keep your credentials safe.

📖 Introduction

Most password managers focus on graphical interfaces, leaving terminal enthusiasts behind. Onilock changes that by offering a sleek, terminal-based user experience paired with a comprehensive set of command-line options.

It’s designed for those working without a graphical interface, users who need quick password access over SSH, or anyone who simply prefers the command line over traditional GUI tools.

With full support for command-line arguments, Onilock empowers users to create custom aliases and streamline password management to fit their unique workflows.

🚀 Features

• Initialize a secure profile using onilock initialize-vault
• Store new accounts with onilock new
• List stored accounts using onilock list
• Copy passwords to clipboard securely with onilock copy
• Remove accounts using onilock remove-account
• Generate strong passwords with onilock generate-pwd
• Export/import vaults with onilock export-vault and onilock import-vault
• Encrypted backups with onilock backup and onilock restore
• Profile management with onilock profiles list|use
• Key management with onilock keys list|delete|rotate-secret
• Environment diagnostics with onilock doctor
• Shell completion support for faster command-line usage

🛠 Installation

OniLock is best installed using pipx to keep it isolated:

1. Install pipx and GnuPG

On macOS, with Homebrew:

brew install pipx gnupg
pipx ensurepath

On Debian/Ubuntu:

sudo apt install pipx gnupg xclip

GnuPG is only needed for encrypted files (encrypt-file, read-file, edit-file and file exports). Password commands work without it. On Linux, onilock copy needs xclip (or wl-clipboard on Wayland). macOS has a built-in clipboard.

If one of these tools is missing, OniLock tells you when a command needs it and offers to install it with your package manager (Homebrew, apt, dnf, pacman or zypper). It shows the exact command and only runs it if you say yes. initialize-vault and doctor run the same check.

2. Install OniLock systemwide

N.B. Make sure you don't have any active virtual environments before executing this command.

pipx install onilock

⚠️ Issues

If you declined an install prompt, or ran OniLock in a script where it can't ask, install the tools yourself:

brew install gnupg               # macOS
sudo apt install gnupg xclip     # Debian/Ubuntu

Over SSH without a graphical session there is no clipboard to copy to, so onilock copy can't work there and OniLock won't offer to install xclip.

onilock doctor checks gpg, the clipboard tool, vim and the vault paths, and offers to install anything missing.

📌 Usage

Once installed, you can use onilock directly from your terminal:

onilock --help

🔹 Initialize OniLock

Before using OniLock, initialize your profile:

onilock initialize-vault

🔹 Add a New Account

onilock new

You will be prompted to enter the account name, username, and password.

🔹 List Stored Accounts

onilock list

Displays all saved accounts.

🔹 Search Accounts

onilock search github
onilock search git --limit 5
onilock search github --json

Fuzzy-searches accounts by name, username, URL, description and tags.

🔹 Copy a Password to Clipboard

onilock copy <account_name>

This copies the password to your clipboard securely.

🔹 Show a Decrypted Secret

onilock show github
onilock show 1 --json

Prints a decrypted secret intentionally for inspection/scripting.

🔹 Account Notes

onilock notes set github --text "Production deployment credentials"
onilock notes get github
onilock notes clear github

Stores and retrieves encrypted per-account notes.

🔹 Account Tags

onilock tags add github prod infra
onilock tags list github
onilock tags remove github infra
onilock tags list --json

Adds, removes, and lists normalized tags per account.

🔹 Password History

onilock history github
onilock history github --limit 5
onilock history github --json

Shows stored password version metadata (newest first).

🔹 Rotate Password

onilock rotate github
onilock rotate github --len 24 --no-special-chars
onilock rotate github --json

Generates a new password, stores it, and pushes the previous secret into history.

🔹 Password Health Report

onilock health github
onilock health --all
onilock health --all --json

Shows health checks for one account or the full vault.

🔹 PIN Unlock Sessions

onilock unlock --pin 1234
onilock pin reset --pin 5678

Adds an optional 4-digit PIN gate for sensitive commands. Leave PIN empty in pin reset to disable. Changing or removing a PIN needs an unlocked session or the master password, and too many wrong PINs lock PIN entry for a few minutes. The PIN doesn't encrypt anything: it stops casual use of an unlocked terminal, not someone with full access to your user account.

🔹 Shell-Safe JSON Output

onilock list --json
onilock list-files --json
onilock doctor --json
onilock doctor --verbose

Use --json for scripting and machine-readable output.

🔹 Secure Imports

onilock import-secrets --format csv --path ./secrets.csv --dry-run
onilock import-secrets --format keepass-xml --path ./keepass-export.xml --replace-existing

Imports secrets from CSV or KeePass XML export, with dry-run preview support.

🔹 Vault Integrity Check/Repair

onilock vault check
onilock vault check --json
onilock vault repair
onilock vault repair --apply --json

Checks for recoverable vault metadata issues and supports dry-run or apply repair flow.

🔹 Remove an Account

onilock remove-account <account_name>

Deletes the stored credentials.

🔹 Generate a Secure Password

onilock generate-pwd

Creates a strong random password.

🔹 Vault Format Version

onilock version

Prints the current vault format version (v2 for AEAD vaults).

Note: In non-interactive environments, initialize-vault and encrypted export/import require explicit flags (e.g., --master-password, --passphrase).

🔒 Security

• OniLock encrypts stored passwords and prevents direct file access.
• Uses the system keyring for secure storage (if available).
• Passwords copied to the clipboard are automatically cleared after a short period.
• Master password protection includes rate limiting and lockouts on repeated failures.
• Exported vaults can be encrypted with a user-provided passphrase.
• An audit log is maintained for key vault events.

Threat Model

OniLock is a local‑only CLI password manager. It does not sync, upload, or transmit vault data. It protects against offline access to the vault files and casual local inspection, but does not protect against a compromised OS, keyloggers, or an attacker with access to the running process. Filenames and timestamps can be visible unless explicitly exported with encryption.

Vault Format & Integrity

Vault data uses a versioned format with AEAD integrity protection (v2 uses AES‑GCM). Legacy v1 data is migrated on successful read.

📘 Advanced Usage

See ADVANCED_USAGE.md for in-depth workflows, export/import formats, and power-user options.

🖥️ Shell Autocompletion

Enable shell autocompletion for easier usage:

onilock --install-completion

📜 License

OniLock is open-source and licensed under the Apache 2.0 License.

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

📝 Changelog

v1.9.0

• Add search, show, rotate, history and health commands.
• Add encrypted per-account notes and per-account tags.
• Add an optional 4-digit PIN that gates sensitive commands.
• Add import-secrets for CSV and KeePass XML, plus vault check and vault repair.
• Add --json output to list, list-files and doctor, and expand doctor.
• Include the v1.8.4 macOS and GnuPG fixes.

v1.8.4

• Fix OniLock crashing on start when GnuPG is not installed (the default on macOS). Password commands now work without gpg.
• Create the PGP key for file encryption on first use.
• Offer to install missing system tools (GnuPG, vim, and xclip or wl-clipboard on Linux) with your package manager, after asking first.
• Add macOS installation steps.

v1.8.0

• Introduce versioned AEAD vault format (v2, AES-GCM) with automatic legacy migration.
• Add export/import encryption, audit logging, and backup/restore workflows.
• Add profile management, key management commands, and environment diagnostics.
• Harden master-password handling with rate limiting, lockouts, and KDF upgrades.
• Add password health checks (entropy, reuse, common password detection) and improved clipboard hygiene.
• Add Poweruser guide and expanded documentation.

v1.7.3

• Fix infinite recursion in remove-account, wrong password length in generate_random_password, and temp file leak in edit-file/read-file.
• Fix AES-CBC IV reuse and weak key derivation in VaultKeyStore; keys are now random and stored in a protected file.
• Fix GPG utility crashes when a key has no UIDs or when deleting a non-existent key.
• Fix Pydantic mutable default shared across model instances.
• Expand test suite to 243 tests; replace observed-behavior assertions with contract-based assertions.

v1.7.2

• Introduce comprehensive test suite with 238 tests achieving 99%+ code coverage.
• Migrate test runner from unittest to pytest with pytest-cov; enforce 95% coverage threshold on every run.
• Overhaul CI/CD pipeline: tests run automatically on PRs and pushes to master; releases and PyPI publication are now fully automated on version bump.
• Add DEVELOPER_GUIDE.md covering setup, testing, and the contribution workflow.

v1.7.0

• Implement file encryption capabilities.
  • Possibility to encrypt any file in your system and add it to the vault.
  • View, and Edit files directly in the vault without exposing them to external threats.
  • Ability to export a single file or all files in the vault to a zip file.
• Introduce env.py to fix the circular import problem.
• Other bug fixes and improvements

v1.6.0

• Fix some bugs.
• Implement support for terminal-based distros.
• Implement git-hub actions for auto-deployment when a new release is created.
• Improve project structure, and implement some design patterns

View full changelog history on CHANGELOG.md file.

📧 Contact

Author: Mouad Kommir
Email: mouadkommir@gmail.com