CLI Password Manager (MVP)

A small, educational command‑line password manager built to practice Python fundamentals, software design, and a disciplined Git workflow. This project is for learning—the initial versions store secrets in plaintext. Do not use for real credentials until encryption is added.

---

Why This Project

This project is a practical lab for becoming a stronger Python/Backend/AI‑automation engineer. It exercises:

• Python basics → functions, modules, and packages
• Clean CLI design with argparse
• File persistence with JSON (then encryption later)
• Error handling and custom exceptions
• OOP refactor into a PasswordManager class
• Git branching and tidy commits

---

Features (MVP → Iterative)

MVP v0.1

• start placeholder command (sanity check)
• add → store a credential (service, username, password) in a JSON file
• get → retrieve one or more credentials by service
• list → show all saved entries
• JSON persistence with atomic writes
• Friendly error messages for missing/corrupt DB

Planned next steps

• OOP refactor (PasswordManager with methods: add, retrieve, list)
• Optional DB path flag (--db-path)
• Basic encryption layer (key management TBD)
• Tests (pytest) and linting (ruff/black)

---

Tech Stack

• Language: Python 3.11+
• Standard Library: argparse, pathlib, json, typing, sys, getpass
• Dev Environment: PyCharm or VS Code, venv, Git, GitHub
• OS: macOS (but code is cross‑platform)

---

Learning Objectives

• Write small, composable modules
• Design a user‑friendly CLI using subcommands
• Persist data safely and handle edge cases
• Use exceptions for clear failure modes
• Practice clean Git habits (branches, focused commits, readable messages)

---

Project Structure (evolving)

password-manager/
├─ password_manager.py      # CLI entrypoint (argparse + subcommands)
├─ storage.py               # JSON persistence helpers (load/save/add/query)
├─ passwords.json           # Data file (created on first save)
├─ README.md                # This file
└─ .gitignore

Later:

password-manager/
├─ password_manager/
│  ├─ __init__.py
│  ├─ cli.py               # CLI wiring
│  ├─ core.py              # PasswordManager class
│  ├─ storage.py           # Persistence strategies
│  └─ crypto.py            # Encryption (future)
└─ tests/

---

Data Model (JSON)

{
  "entries": [
    { "service": "github", "username": "alice@example.com", "password": "plain-for-now" }
  ]
}

Notes:

• Top‑level entries list keeps schema flexible (easy to add fields later)
• Atomic writes via temp file → replace, to avoid corruption

---

CLI Design (MVP)

Usage examples:

# Start / hello‑world check
python password_manager.py --start

# Add a credential (plaintext for MVP)
python password_manager.py add --service github --username you@example.com --password secret

# Retrieve by service (may return multiple)
python password_manager.py get --service github

# List everything
python password_manager.py list

Planned flags:

• --db-path PATH → optional alternate DB location
• --format json|table → output formatting (later)

---

Setup

Requirements

• Python 3.11+
• Git

Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate   # Windows

Install dependencies MVP uses only the standard library. When encryption is added: pip install cryptography.

Run

python password_manager.py --start

---

Development Workflow

Initialize Git & push

git init
git add .
git commit -m "Initial commit: basic CLI setup"
git branch -M main
git remote add origin https://github.com/<you>/cli-password-manager.git
git push -u origin main

Branching model (simple)

• main → stable, working
• Feature branches → feat/subcommands, feat/encryption, fix/corrupt-json

Commit message style

• Imperative, focused: Add JSON storage helpers, Handle corrupt DB gracefully

---

Error Handling Strategy

• Graceful first‑run: missing file returns empty DB
• Corrupt JSON → warn, fall back to empty; never crash the CLI
• I/O issues → raise StorageError with actionable message

---

Security Notes

• MVP stores passwords in plaintext (educational only). Do not use real credentials.
• Encryption will be added in a later milestone. Even then, treat this as a learning tool, not a production vault.

---

Roadmap (Condensed from Week Plan)

1. CLI bootstrap with argparse (done)
2. JSON persistence (load/save/add/query)
3. Error handling & custom exceptions
4. Subcommands wired to storage
5. OOP refactor (PasswordManager)
6. Git branching exercise
7. Basic encryption & README polish

---

License

MIT

---

Acknowledgements

Inspired by project‑driven learning and Python’s excellent standard library. This repo exists to build engineering instincts through repetition and iteration.