pyjournaling 1.0.0

An encrypted, colorful terminal journal

PyJournal

A colorful, encrypted, password-protected terminal journal written in Python.

Features

• End-to-end encryption — entries are encrypted with a random master key using Fernet (AES-128-CBC). The master key is never stored in plaintext.
• Password-derived security — your password unlocks the master key via PBKDF2-SHA256 (480,000 iterations). No password = no access.
• Recovery code — a one-time 160-bit recovery code is generated at setup. If you forget your password, use it to recover access without losing any entries.
• Rich terminal UI — colored panels, styled menus, and visual separators powered by Rich.
• Change password — re-wraps the master key with your new password. Journal entries are untouched.
• Delete entries — password-confirmed deletion of individual entries.
• Entry counter — tracks total number of journal entries.

Security model

password  ──► PBKDF2-SHA256  ──► wrapping key  ──► decrypts  ──► MASTER KEY
                                                                      │
recovery code  ──► PBKDF2-SHA256  ──► wrapping key  ──► also decrypts ┘
                                                                      │
                                                               encrypts entries

What is stored in ~/.pyjournal/.env:

Key	Purpose	Secret?
SALT	KDF salt for password path	No
RECOVERY_SALT	KDF salt for recovery path	No
TOKEN	bcrypt hash for fast login	No
ENCRYPTED_MASTER	master key wrapped with password-derived key	Not without your password
RECOVERY_MASTER	master key wrapped with recovery-code-derived key	Not without your recovery code

The encryption key is never stored on disk. An attacker with access to your files cannot decrypt your entries without your password or recovery code.

Requirements

• Python 3.10+
• See requirements.txt for dependencies

Installation

Development

# Clone and set up a virtual environment
git clone https://github.com/your-username/pyjournal.git
cd pyjournal

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

pip install -r requirements.txt
python journal.py

Via pipx (recommended for end users)

pipx install pyjournal
pyjournal

Usage

pyjournal                   # launch the journal
pyjournal --reset-password  # recover access using your recovery code

On first launch you will be asked to create a password. Your recovery code is displayed once — write it down and store it somewhere safe.

Menu options

Option	Action
1	New log entry
2	Read previous logs
3	Exit
4	Show all options
5	Change password
6	Change display name
7	Delete an entry

Forgot your password?

pyjournal --reset-password

Enter your recovery code when prompted. You will be able to set a new password and all existing journal entries will be preserved.

If you have lost both your password and your recovery code, your entries cannot be recovered. This is by design.

Data location

All data is stored in ~/.pyjournal/:

File	Contents
.env	Salts, token, and encrypted master key blobs
something.txt	Encrypted journal entries
saves.txt	Entry count