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.
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.
cargo install ntropyPre-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.
# 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:doneNew 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.
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/.
git clone https://github.com/jakobwesthoff/ntropy.git
cd ntropy
cargo build --release
cargo install --path . # install your working copy onto your PATHCommon 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 ./distThe 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 snapshotsThe 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.htmlThe 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).
ntropy is licensed under the Mozilla Public License 2.0. See LICENSE.
Copyright (c) 2026 Jakob Westhoff jakob@westhoffswelt.de