Paman (Password Manager)

A secure, CLI-based password manager built with Python, SQLAlchemy, and cryptography.

Features

• Secure Encryption: Uses Argon2id for password hashing and Fernet (AES-128) for data encryption.
• Master Account System: Single master password protects all credentials.
• Hierarchical Storage: Organizes credentials by Domains (e.g., github.com).
• Zero-Knowledge Architecture: The database stores only encrypted values; encryption keys are derived from the master password at runtime and never stored.

Installation

Recommended: Install globally using uv (modern replacement for pipx):

# Install from source
uv tool install . --force

# Run commands
paman --help

Alternatively, you can run it ephemerally without installing:

uvx --from . paman --help

Uninstallation

To remove the application:

uv tool uninstall paman

To remove all configuration and data, run this before uninstalling:

paman uninstall --full

Configuration

Paman loads configuration from environment variables. These can be set in your shell or in a .env file located in the config directory.

Config Location: ~/.config/paman/.env (on Linux)

Precedence

1. PAMAN_DATABASE_URL (Highest priority)
2. TURSO_DATABASE_URL (For LibSQL/Turso support)
3. DATABASE_URL (Standard fallback)
4. Local SQLite (Default: ~/.local/share/paman/paman.db)

To use a custom database, edit ~/.config/paman/.env after installation:

# Example .env
PAMAN_DATABASE_URL=sqlite:////path/to/secure/drive/paman.db

Usage

Running Tests

uv run pytest

Development

This project uses uv for package management.

• src/paman/core/crypto: Cryptographic primitives (KDF, Hashing).
• src/paman/core/db: Database models (User, Domain, Credential).
• src/paman/core/logic: Business logic and services.

Security

See SYSTEM_DESIGN.md for a detailed breakdown of the security architecture.