Zecret

A modern, encrypted terminal diary.

One entry a day, in your terminal, kept in a single encrypted file that only you can open.

zecret.krfu.dev · Install · How it works

Why

A diary should be private by construction, not by promise. Zecret has no server, no account, no sync and no telemetry — there is nowhere for your writing to go. It is one encrypted file on your own disk, opened by a password only you know, in a terminal you already have open.

• 📅 One entry a day — each day is a page, named by its date; come back and it is the same page
• 🗓️ Grouped by month — the diary reads as months, each headed with how much of it you wrote
• 🔐 Encrypted at rest — Argon2id key derivation, AES-256-GCM per entry
• ✍️ Keyboard-driven — a fast Textual TUI, no mouse required
• 🔎 Instant search — live filtering across everything you have written
• 📄 One portable file — back it up by copying it; it is useless without your password
• 🌗 Light and dark — eight themes, picked in settings and remembered
• 🔒 Locks itself — walks away when you do, and asks for your password again
• 🚫 Offline by design — no networking of any kind

Install

uv tool install zecret
zecret

That is the whole of it: uv fetches a suitable Python along with the program, so nothing depends on what your system happens to ship. If you would rather use what you already have, pipx install zecret and pip install zecret both work on Python 3.13 or newer.

Your diary lives at ~/.zecret/diary.enc by default. Point somewhere else with --path /some/where.enc or the ZECRET_DIARY_PATH environment variable — handy for keeping separate diaries, or trying it out without touching your real one.

Your settings follow you rather than the file, so a diary opened with --path still uses your theme. If you would rather it did not — running a build you are working on, say — --config /some/where.json or ZECRET_CONFIG_PATH gives that run preferences of its own.

zecret --help lists both flags and both environment variables, and zecret --version says which Zecret you have without opening the diary.

On first launch there is no diary yet, so Zecret asks you to choose a master password and creates one. Every launch after that asks for that password to unlock it.

[!WARNING] There is no password recovery, by design. Nobody — including you — can open the file without the password. Choose something you will not lose.

Using it

Press n to write about today, ctrl+s to save. A day holds one entry, so pressing n again later opens what you already wrote rather than starting a second page — the evening simply continues the morning. Every save re-writes the diary file atomically, so there is no draft state to lose track of.

Missed a day? Press a and type the date. Anything up to today is fair game; days that have not happened yet are refused.

Press / to search. Your entries are already decrypted in memory for the session, so filtering is instant and nothing touches the disk.

Press ? for every key in one popup, and s for settings — where you pick a theme, choose how long the diary waits before locking itself, and change your master password. Those preferences are kept in ~/.zecret/config.json, the one file Zecret writes unencrypted; it holds your settings and nothing about what you wrote.

Zecret locks itself after fifteen minutes without a keystroke, and asks for your password again — press ctrl+l to do it yourself on the way out of the room. It works while you are writing, too, and saves the day before locking it away: the alternative would be a question sitting on the screen with the diary open behind it. A half-written entry holds the timer off rather than being thrown away by it. Change the wait, or turn it off, in settings.

Keys

Getting around a long diary: j/k or the arrow keys move a day at a time, g/G (or home/end) jump to the newest and oldest entries, and PgUp/PgDn move a screenful. These stay out of the bar at the bottom, which only has room for so much — ? lists everything.

How it works

• Key derivation — Argon2id (time_cost=3, memory_cost=64 MiB, parallelism=4, roughly OWASP interactive settings), with a random 16-byte salt generated per diary and stored in the file header. Your password is never stored; the derived key never touches disk.
• Encryption — AES-256-GCM with a fresh random nonce for every encryption. Each day's entry is encrypted independently, so editing one day never re-encrypts the others. Only the dates are visible in the file; every word you write is inside the ciphertext.
• Integrity — tampering with a stored entry, or a wrong password, fails the AEAD authentication check and is reported as an error, never as an empty or partial diary. The header carries an encrypted verifier, so this holds even for a diary with no entries yet.
• Durability — saves are atomic (temp file → fsync → os.replace), so an interrupted save can never leave a half-written diary. Creating a diary instead claims the path with O_EXCL, so two first runs racing each other cannot end with one written over the other; a creation that fails removes what it started. The file is created 0600.

Plaintext is never written to disk — not as temp files, not as logs, not for crash recovery.

Development

git clone https://github.com/kfurtak1024/zecret.git
cd zecret
uv sync            # dev tools included (PEP 735 dependency group)
./zecret-dev.sh    # run it against a throwaway diary
uv run pytest
uv run ruff check . && uv run ruff format .
uv run mypy

Note ./zecret-dev.sh rather than uv run zecret. Running the app from a checkout opens your own diary with whatever code is currently checked out, which is not what you want a half-finished change doing. The script points the app at .zecret-dev/ instead — gitignored, throwaway, and seeded on first run with a few hundred generated days so there is enough in it to see a layout problem. The password is dev. Delete the directory whenever you like; the next run rebuilds it.

It overrides the preferences file as well as the diary, which matters more than it sounds: without that, trying themes out in a development build changes the theme in the one you write in.

uv run python tools/seed_dev_diary.py --help    # different data, same guardrails

The screenshots above are generated, not taken by hand — regenerate them after any change that alters what a screen looks like:

uv run python tools/screenshots.py    # needs librsvg or inkscape

CI runs those same checks on every push and pull request. uv.lock is committed and CI installs from it, so regenerate and commit it whenever pyproject.toml changes.

License

MIT © Krzysztof Furtak — see LICENSE.