Skip to content

About

puny manager is a CLI password manager

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

Description

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)

Security

  • 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.)

Installation

Recommended method using the aur:

paru -S puny-manager

Using pipx:

pipx install git+https://github.com/Vaspyyy/puny-manager.git

The pipx installation is password-only. Facial unlock requires the root-owned system integration shipped by the Arch/AUR package.

Updating

If installed via aur:

paru -Syu

If installed via pipx:

pipx upgrade puny-manager

Shell completions

Bash

cp completions/puny-manager.bash ~/.local/share/bash-completion/completions/puny-manager

Or source it directly:

source completions/puny-manager.bash

Zsh

cp completions/_puny-manager ~/.local/share/zsh/site-functions/_puny-manager

Or add completions/ to your $fpath in .zshrc:

fpath=($(pwd)/completions $fpath)

Fish

cp completions/puny-manager.fish ~/.config/fish/completions/puny-manager.fish

Usage

Change language (en, de, fr, es, ru, pt, zh):

puny-manager lang        # lists available languages
puny-manager lang de     # switches to German

Vault management

Create 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 unlock

Master 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 vault

Howdy facial unlock

Howdy 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.socket

Then enroll the active vault:

puny-manager howdy test
puny-manager howdy enable
puny-manager howdy status

Protected 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 disable

The 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.socket and puny-manager-howdy@.service into /usr/lib/systemd/system/
  • puny-manager-howdy.pam as /etc/pam.d/puny-manager-howdy
  • puny-manager.tmpfiles as /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.

Passwords & entries

Add a new entry:

puny-manager add                        # interactive prompts
puny-manager add --generate             # auto-generates password
puny-manager add --generate --length 32 # custom length

You can store optional URL and tags for entries.

List stored entries:

puny-manager list

Retrieve an entry (password is copied to clipboard):

puny-manager get <name>

Set clipboard clear timeout:

puny-manager get <name> --timeout 30

The 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 gen

Change master password:

puny-manager passwd

Edit an entry:

puny-manager edit <name>                # interactive
puny-manager edit <name> --generate     # regenerate password

Remove an entry:

puny-manager rm <name>

Audit

Check vault health and password hygiene:

puny-manager stats

Shows entry count, weak passwords, duplicate detection, and tag breakdown without revealing any actual passwords.

Export/Import

Export vault to JSON:

puny-manager export vault.json

Export vault to CSV:

puny-manager export vault.csv --csv

Import vault from JSON:

puny-manager import vault.json

Import vault from CSV:

puny-manager import vault.csv --csv

Custom Fields

Add entries with custom key-value fields:

puny-manager add
# When prompted: Custom fields (key=value, comma-separated, optional): api_key=abc123, recovery_code=xyz

Edit custom fields:

puny-manager edit <name>

Tags Filtering

List entries filtered by tag:

puny-manager list --tag work

Configuration

View current configuration:

puny-manager config

Set configuration values:

puny-manager config default_length 32
puny-manager config backup_count 10
puny-manager config clipboard_timeout 30

These settings control generated password length (minimum 8), backup retention, and the default get clipboard timeout. Explicit command options take precedence.

Backups

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.

About

puny manager is a CLI password manager

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages