duras is a command-line tool for daily notes as plain text files, with built-in search, #tags, and optional encryption. It's written in OCaml — a language renowned for its reliability and correctness, used in mission-critical software where precision and robustness are paramount.
duras stores everything locally, runs as a native binary with no runtime dependencies, and is designed for terminal users who want a note-taking system that stays out of the way. It explicitly doesn't sync across devices, offer a GUI, or require a database — if you need those, a different tool would serve you better.

Classifiers

Operating System

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.

Commands

📝 duras open
📓 duras list
👁️ duras show
✍️ duras append
🔎 duras search
🏷️ duras tags
📈 duras stats
📆 duras echo
🗓️ duras near
➡️ duras mv
📦 duras export
✅ duras audit

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, modify, and distribute without any restrictions. Source code at Codeberg.
Documentation: A man page is included with the OCaml installation. Source and full documentation at Codeberg.
Instant startup: A native binary with no interpreter to start. duras today completes in under a millisecond. Common commands feel immediate.
Notes survive without duras: If duras disappeared tomorrow, every note would remain readable. Plain UTF-8 text, standard directory layout, accessible with cat, grep, or any text editor. No recovery step. No export needed.
Formally specified: Behaviour is defined by a written specification covering the filesystem layout, every command, and the encryption model. The spec is the contract — not the source code.

Built to last

Multiple implementations

duras has been independently implemented in OCaml (primary), Python (maintained, on PyPI), and C (complete, frozen). All three pass the same compatibility test suite. Notes written by one are readable by another.

Compatibility test suite

121 black-box tests verify exit codes, output fields, filesystem state, atomic write safety, and encryption behaviour. Any future implementation of duras can be verified against the same suite.

Scope discipline

duras has a published scope boundary — a list of things it will never become. No sync. No database. No plugins. No background services. Every addition must answer: does this make the data more durable or trustworthy in 10 years?

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.

No runtime dependencies

duras is a native binary. No interpreter, no virtual machine, no package ecosystem to keep up to date. Install it, and it runs. The only optional dependency is gpg, used only for encrypted notes.

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

Native binary. No runtime required. gpg is optional — used only for encrypted notes.

Linux (x86_64)

curl -L \
  https://codeberg.org/duras/duras/releases/download/v2.0.0/duras-linux-amd64 \
  -o ~/.local/bin/duras &&
chmod +x ~/.local/bin/duras

macOS (Apple Silicon)

curl -L \
  https://codeberg.org/duras/duras/releases/download/v2.0.0/duras-macos-arm64 \
  -o /usr/local/bin/duras &&
chmod +x /usr/local/bin/duras

macOS (Intel)

curl -L \
  https://codeberg.org/duras/duras/releases/download/v2.0.0/duras-macos-amd64 \
  -o /usr/local/bin/duras &&
chmod +x /usr/local/bin/duras

macOS may block unsigned binaries. If a security warning appears: xattr -d com.apple.quarantine /usr/local/bin/duras

Build from source

Requires OCaml and dune.

git clone https://codeberg.org/duras/duras.git
cd duras
make install           # installs to /usr/local

Also available for Python users: pip install duras — see duras-python.

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)

Interested in contributing?

duras is open source under the ISC License. That means you can read the code, modify it, fork it, and build something new with it — no permission needed.

If you want to contribute to the project itself, the most useful things are: bug reports with clear reproduction steps, fixes for real problems, and improvements that fit the existing design. The project has a published specification and a compatibility test suite — any implementation that passes the suite is a valid duras.

If you want to implement duras in a different language, that is genuinely welcomed. The specification exists precisely for this. The C and OCaml implementations were both built from the spec, not from copying the Python source.

If you just want to fork it and make something different — that is what the license is for. No need to ask.

Source: codeberg.org/duras/duras · Mirror: github.com/sduras/duras