duras

plain-text daily notes · filesystem as index · no database

duras is a lightweight command-line tool for managing daily notes as plain text files, with built-in search functionality and optional encryption. It's designed for developers and terminal-focused users who want a minimal note-taking system that stores everything locally. It explicitly isn't designed for syncing across devices, GUI editing, or complex database queries — if you need those features, a different tool would be more appropriate.

Classifiers

Operating System

  • OpenBSD icon OpenBSD
  • Debian
  • macOS

The tool is fundamentally Unix-oriented, so it's at its best on GNU/Linux, BSD & macOS.

Text Editors

duras is a standalone tool, but most effectively used together with minimal Vim / Neovim plugin that integrates the CLI directly into the text editor.

Notes Format

Plain UTF-8, LF line endings, the most portable and reliable digital format in existence. Readable with any text tool. No proprietary lock-in.

bash
Durable by default
Notes written today are accessible in 10 years regardless of software changes.
Version control friendly
Plain text files work perfectly with Git and other version control systems.
Terminal-based
Low resource usage, high keyboard-driven productivity, and automation capabilities.
Unix-native
Works with grep, awk, sed, git, diff, and tar without conversion or export.
Privacy & control
All data stays locally; users can choose to encrypt notes with GnuPG for added security.
Free software
Released under the ISC License, free to use and modify without any restrictions.
Documentation
Full reference available on Read the Docs, with a man page included in the package.

Technical reliability

Atomic writes

Every note is written to a temporary file, synced to disk with fsync, then renamed atomically. A crash never leaves a half-written file.

No hidden state

No index files, no databases, no metadata beyond the notes themselves. The directory layout is the data structure. ls is the query engine.

Strict permissions

The notes directory is set to 0700 on first run. Encrypted notes use 0600. No broader filesystem exposure than necessary.

Predictable exit codes

Five distinct exit codes — success, error, not found, invalid input, external failure — making duras composable in shell scripts and pipelines.

Zero dependencies

Pure Python with no external libraries (except optional GnuPG). Guaranteed to work on any system where a Python is installed without requiring internet access.

Strong cryptography

Confidential notes use system gpg. Encrypted append is memory-only — no plaintext touches disk. The temp file for editing prefers /dev/shm.

Installation

Requires Python 3.9 or later. No external dependencies. gpg is optional — used only for encrypted notes. 

pip install duras

duras                          # open today's note in $EDITOR
duras append "first entry"     # append without opening editor
duras list                     # see recent notes

Environment

DURAS_DIR Notes directory  (default: ~/Documents/Notes)
EDITOR Editor to open notes  (fallback: nano, vi, ed)
DURAS_GPG_KEY GPG recipient for encryption  (default: self)