ntropy

An opinionated Markdown note-taking and management CLI where metadata, not folders, is the filing system. No database, no proprietary app, no folder hierarchy to maintain by hand: plain Markdown files and their frontmatter.

The short version: write Markdown, tag it, and let ntropy do the filing. Fuzzy full-text search, a query language, browsable views materialized straight into your filesystem, editor-native link and tag completion over LSP, PDF and website export, and no database pretending to be a note app.

The documentation lives at https://ntropy.westhoffswelt.de; this file is the entry point: install, first steps, and how to work on ntropy itself.

Why I built this

I live on the command line and in Neovim, and every note app I tried wanted me back inside its own (usually graphical) UI to make sense of files it nominally stored as plain text. I wanted the inverse: notes that are just Markdown files, a CLI to manage them, and nothing stateful in between. ntropy is the heavily opinionated result. Notes live flat in one vault, a note's identity is a stable ULID rather than its title, and any hierarchy you browse is a derived projection of the frontmatter instead of the canonical storage. Switching vaults is cheap, one for work, one for private, or a per-project vault pinned by a .ntropy-vault file in a repo, so documenting a project is the same motion as any other note. It scratched my itch; maybe it scratches yours.

Installation

cargo install ntropy

Pre-built binaries

Pre-built binaries are available on the GitHub Releases page for macOS (Apple Silicon & Intel) and Linux (x86_64 & aarch64, statically linked).

[!NOTE] ntropy supports macOS and Linux. Windows is not supported; see Limitations.

Quick start

# Scaffold a vault (this also seeds a by-tag view)
ntropy init ~/notes
cd ~/notes

# Create a note from a template and open it in your editor
ntropy new My first note

# Open today's daily note (created on first use each day)
ntropy today

# Find and open notes: full query language, fuzzy picker when several match
ntropy search tag:work and not status:done

New notes are stamped out from templates; today has its own daily template; and search speaks a small query language, opening an interactive picker when more than one note matches.

You never have to tell ntropy which vault you mean from inside one; it finds it for you.

Documentation

The full documentation is a website that ntropy exports from the vault under docs/website/ in this repository, so it reads the same as any vault you publish yourself:

Getting started: installation, first steps, a tour, and the command reference.
Notes and the vault: the note format, Markdown, templates, finding the vault, views, encryption, and configuration.
Finding notes: the query language and the interactive picker.
Publishing: rendering to PDF and HTML, document themes, exporting a website, and site themes with their templates.
Integrations: the language server, scripting and the shell, and the agent skill.
Development: building ntropy, its limitations, and the design records.

The design itself is recorded as decision records under docs/adr/ and narrative documents under docs/design/.

Development

git clone https://github.com/jakobwesthoff/ntropy.git
cd ntropy
cargo build --release
cargo install --path .   # install your working copy onto your PATH

Common tasks are wrapped as just recipes (just --list):

just test      # cargo test
just clippy    # cargo clippy --all-targets -- -D warnings
just fmt       # cargo fmt
just check     # clippy + tests + fmt --check (the CI gate)
just coverage  # cargo llvm-cov
just site-check  # rebuild the site frontend with Bun, check, lint, and test it (the CI gate)
just website   # export the documentation vault as the project website into ./dist

The browser-side code of the site export lives in site/ and is built with Bun; just site-build writes the result to src/site/dist/, which is committed. cargo build never runs Bun.

Tests use insta snapshots across all layers (ADR 0021). When a change alters output, the snapshot assertions fail and write .pending-snap files; review and accept them with cargo-insta:

cargo insta review   # interactively accept/reject pending snapshots
cargo insta accept   # accept all pending snapshots

Project page

The project page at https://ntropy.westhoffswelt.de is the documentation vault under docs/website/, exported by ntropy itself. A push to main that touches docs/website/, and every release, rebuilds and deploys it through .github/workflows/pages.yml, which exports the vault with the newest released binary; CI exports it with the commit's own build, so a change that breaks the export fails there first. To build it with your working copy:

just website         # exports docs/website into ./dist
open dist/index.html

The vault is an ordinary ntropy vault: ntropy --vault docs/website new, search, and write work on it, and its .ntropy/config.toml holds the site's title, front page, and sidebar root. The demo recording in docs/website/assets/ is produced by docs/vhs/record.sh (see docs/vhs/README.md).

License

ntropy is licensed under the Mozilla Public License 2.0. See LICENSE.

ntropy 2.1.1