duras

Daily notes as plain text files, with search and optional encryption.

Optional Vim/Neovim integration: duras_bridge.

Install

pip install duras

Requires Python 3.9 or later. No dependencies. gpg optional for encrypted notes.

Quick start

duras                          # open today's note in $EDITOR
duras append "fix login bug #todo"
duras search todo
duras tags

Note format

One file per day, stored as plain UTF-8 text:

~/Documents/Notes/YYYY/MM/YYYY-MM-DD.dn

Self-describing without filename or directory context:

date: 2026-04-28

2026-04-28 09:10  started work
2026-04-28 14:32  fix null check in login handler #todo
2026-04-28 16:00  called bank re: account — follow up Thursday

Header is one line. Entries are timestamped lines separated from text by two spaces. Writes are atomic. The filesystem is the index; there is no hidden state.

Encrypted notes are stored as YYYY-MM-DD.dn.gpg via the GNU Privacy Guard.

Scope

Fits terminal workflows, grep-based retrieval, long-lived plain text, and optional encryption. Not a sync system, GUI, rich-text editor, or query engine.

Commands

open

duras               # today
duras open -1       # yesterday
duras open 2026-04-19
duras open -- +10   # pass +10 to $EDITOR (jump to line)

append

duras append "text"
duras append -d -1 "yesterday"
cat file | duras append
cmd | duras append

Text argument is optional. When omitted, stdin is read automatically.

show

duras show
duras show -1

list / stats

duras list
duras list -n 0     # all notes
duras stats

Order: by filename (ISO date), not mtime.

search / tags

duras search error
duras search todo -i    # case-insensitive
duras tags              # all tags with counts
duras tags project      # notes containing #project

Literal match, not regex. Encrypted notes excluded.

export

duras export ~/backup
duras export ~/backup --encrypt

Creates a timestamped .tar.gz. --encrypt pipes through gpg; no plaintext archive is written.

utilities

duras path          # absolute path to today's note
duras dir           # notes root directory
duras today         # print today's date
duras audit         # validate directory structure
duras echo          # notes on this date in past years
duras near          # notes within ±3 days of today
duras mv 2026-04-17 2026-04-16

Encryption

duras -c open
duras -c append "secret"
duras -c show

• uses system gpg
• append -c is memory-only; no plaintext temp file
• open -c writes a temp file to /dev/shm when available
• encrypted notes are excluded from search and tags

Dates

YYYY-MM-DD   absolute
0            today
-1           yesterday
-7           one week ago

Future dates are rejected.

Environment

variable	meaning
DURAS_DIR	notes directory (default: ~/Documents/Notes)
EDITOR	editor (fallback: nano, vi, ed)
DURAS_GPG_KEY	GPG recipient (default: self)

.editorconfig is written to the notes directory on first run. It configures supporting editors to use UTF-8, LF line endings, and 72-column line length for .dn files.

Exit codes

code	meaning
0	ok
1	error
2	not found
3	invalid input
4	external failure

Documentation

• man duras
• duras --help
• https://duras.readthedocs.io/en/stable/

Licensed under the ISC License. See LICENSE.