HumPass – Terminal Password Manager

HumPass is a minimal, secure password manager designed for terminal usage. It focuses on simple workflows, encrypted local storage and fast command execution. A master password protects the entire vault, and onboarding guides first-time setup.

Prerequisites

• Go: install a Go version compatible with go.mod (see the go line in go.mod)
• macOS:
  • Keychain access (optional, used for auto-login key storage)
  • Clipboard access (used by search to copy the password)

Feature Checklist

Core (Must-have)

• Create password entries (title, username, password)
• Search entries by keyword
• Edit existing entries
• Delete entries
• Encrypt all stored data locally
• Require a master password to unlock the vault
• Provide CLI commands (add, search, list, remove)
• Display clear error messages for invalid input
• Onboarding on first launch to set up master password

Optional (Nice-to-have)

• Copy password to clipboard
• Automatically clear clipboard after 15 seconds
• Generate secure passwords automatically
• Require master password only every 15 minutes (timeout)
• Extra protection against file tampering

---

Project Goal

HumPass aims to deliver a simple but secure console-based password manager. It focuses on usability, encryption and reliability without relying on external services.

Technology Stack

• Language: Go
• Architecture: MVC-style
• Storage: Local encrypted file

Getting Started

Install (recommended: install.sh)

From the project root:

chmod +x install.sh
./install.sh

What it does:

• Builds the binary: go build -o humpass ./cmd/humpass/
• Installs it to: ~/bin/humpass
• Data location: ~/.humpass/data.json

Ensure ~/bin is in your PATH

If install.sh warns that ~/bin is not in your PATH, add this to your shell config (~/.zshrc or ~/.bash_profile):

export PATH="$HOME/bin:$PATH"

Reload your shell:

source ~/.zshrc

Build (manual)

go build -o humpass ./cmd/humpass/

Run

./humpass --help

On the first launch, HumPass will guide you through creating your master password and initial configuration.

CLI Commands

Tip: run humpass --help for a full list and examples.

humpass add --title Google --username alice --password 'Secret123' --link google.com
humpass create --title GitHub --mail alice@mail.com --password 'Secret123' --link github.com

humpass search Google
humpass search --title Google
humpass search --mail alice@mail.com
humpass search --link github.com

humpass edit Google

humpass delete Google
humpass remove Google

Data & security notes

• Encrypted entries are stored in ~/.humpass/data.json under encryptedEntries
• Entries are encrypted using AES-GCM
• The app enforces a simple lockout: after 5 failed login attempts you’re locked for 30 minutes

Reset / uninstall

Remove the binary

rm -f "$HOME/bin/humpass"

Remove local data

rm -rf "$HOME/.humpass"

Remove the Keychain item (macOS)

HumPass stores the auto-login key under:

• Service: humpass-cli
• Account: master-sessions-key

Delete it:

security delete-generic-password -s "humpass-cli" -a "master-sessions-key"