Puny Manager is a minimal, local, CLI password manager for Linux.
It stores all passwords in a single encrypted vault file protected by a master password. Enrolled vaults may also be unlocked through a TPM-backed Howdy credential.
Note: To use clipboard feature you need wl-clipboard (wayland) or xclip (x11)
- Vault encryption: AES-256-GCM
- Key derivation: Argon2id (with legacy PBKDF2-HMAC-SHA256 support)
- Configurable encryption level: fast (32MB), balanced (64MB, default), paranoid (256MB)
- Versioned binary format with header validation
- Every protected command authenticates independently
- Optional Howdy facial unlock with master-password recovery (Arch system package)
- No unlocked session or authentication caching
- The vault file is binary and unreadable if opened directly
- Rotating backups on save (
<name>.puny.bak.1, etc.)
Recommended method using the aur:
paru -S puny-managerUsing pipx:
pipx install git+https://github.com/Vaspyyy/puny-manager.gitThe pipx installation is password-only. Facial unlock requires the root-owned system integration shipped by the Arch/AUR package.
If installed via aur:
paru -SyuIf installed via pipx:
pipx upgrade puny-managercp completions/puny-manager.bash ~/.local/share/bash-completion/completions/puny-managerOr source it directly:
source completions/puny-manager.bashcp completions/_puny-manager ~/.local/share/zsh/site-functions/_puny-managerOr add completions/ to your $fpath in .zshrc:
fpath=($(pwd)/completions $fpath)cp completions/puny-manager.fish ~/.config/fish/completions/puny-manager.fishChange language (en, de, fr, es, ru, pt, zh):
puny-manager lang # lists available languages
puny-manager lang de # switches to GermanCreate a new vault:
puny-manager create personal # balanced encryption
puny-manager create secrets --level paranoid # 256MB Argon2id
puny-manager create throwaway --level fast # 32MB, quicker unlockMaster passwords must be at least 4 characters. For existing v1.x users: your vault auto-migrates on first run.
Manage vaults:
puny-manager vault list # list all vaults (* = active)
puny-manager vault switch <name> # change active vault
puny-manager vault delete <name> # remove a vaultHowdy support is optional, Linux-only, and configured separately for each vault.
It requires Howdy, TPM 2.0, python-pam, and the Arch system package assets.
Enable the one-shot authentication socket once:
sudo systemctl enable --now puny-manager-howdy.socketThen enroll the active vault:
puny-manager howdy test
puny-manager howdy enable
puny-manager howdy statusProtected commands now try facial recognition first and fall back to the master
password on failure. Supplying --master-password bypasses Howdy. Disable it
and return the vault to the password-only format with:
puny-manager howdy disableThe master password remains required for enrollment, removal, recovery, and password changes. TPM loss, a broken camera, or a missing helper never prevents master-password recovery. Facial unlock does not protect against root compromise, a compromised running session, or same-user malware that waits for a successful face check.
Arch packagers install the files from packaging/arch/ as follows:
puny-manager-howdy.socketandpuny-manager-howdy@.serviceinto/usr/lib/systemd/system/puny-manager-howdy.pamas/etc/pam.d/puny-manager-howdypuny-manager.tmpfilesas/usr/lib/tmpfiles.d/puny-manager.conf
The package should list Howdy and python-pam as optional dependencies and run
systemd-tmpfiles --create puny-manager.conf during installation.
Add a new entry:
puny-manager add # interactive prompts
puny-manager add --generate # auto-generates password
puny-manager add --generate --length 32 # custom lengthYou can store optional URL and tags for entries.
List stored entries:
puny-manager listRetrieve an entry (password is copied to clipboard):
puny-manager get <name>Set clipboard clear timeout:
puny-manager get <name> --timeout 30The clear runs after the command exits and only clears content that still matches
the copied clipboard value. Use --timeout 0 to disable clearing.
Generate a new password:
puny-manager genChange master password:
puny-manager passwdEdit an entry:
puny-manager edit <name> # interactive
puny-manager edit <name> --generate # regenerate passwordRemove an entry:
puny-manager rm <name>Check vault health and password hygiene:
puny-manager statsShows entry count, weak passwords, duplicate detection, and tag breakdown without revealing any actual passwords.
Export vault to JSON:
puny-manager export vault.jsonExport vault to CSV:
puny-manager export vault.csv --csvImport vault from JSON:
puny-manager import vault.jsonImport vault from CSV:
puny-manager import vault.csv --csvAdd entries with custom key-value fields:
puny-manager add
# When prompted: Custom fields (key=value, comma-separated, optional): api_key=abc123, recovery_code=xyzEdit custom fields:
puny-manager edit <name>List entries filtered by tag:
puny-manager list --tag workView current configuration:
puny-manager configSet configuration values:
puny-manager config default_length 32
puny-manager config backup_count 10
puny-manager config clipboard_timeout 30These settings control generated password length (minimum 8), backup retention,
and the default get clipboard timeout. Explicit command options take precedence.
Vaults are automatically backed up before each save with rotating backups (5 by default).
Backups are stored as vault-name.puny.bak.1, vault-name.puny.bak.2, etc.
Set backup_count to 0 to disable backups. Reducing the count prunes excess
numbered backups on the next save. Deleting a vault also deletes its backups;
a successful master-password change removes backups encrypted with the old password.