nb Notes

Last reviewed Aug 26, 2026 · 854 words

nb is not a server. It is a single Bash script, about 8,400 stars' worth of one, that turns a directory of Markdown files into a notebook with search, tags, bookmarks, encryption and versioning. If you already keep everything in Vim and a Git remote, it is the most complete plain-text notes tool I know. If you want a phone app or a web page with a sidebar, stop reading and pick Joplin or Trilium instead.

Where nb sits in a self-hosted stack

The "self-hosted" part of nb is the Git remote. Every notebook is a Git repository under ~/.nb, and every nb add, nb edit or nb delete is a commit. Point a notebook at a remote and nb sync becomes push-and-pull:

nb remote set [email protected]:me/notes.git
nb set auto_sync 1

That remote can be Gitea or Forgejo on a 512 MB VPS, a bare repository over SSH on a NAS, or a private GitHub repo if you do not care about hosting it yourself. nb does not need a database, a daemon or a port. The 32 MB RAM figure in the catalogue is the memory of a shell process; the real requirement is Bash 4 or later and Git.

Install is one line on most systems: brew install xwmx/taps/nb on macOS, npm install -g nb.sh, or the curl-to-/usr/local/bin route from the project page. Optional dependencies add features rather than gate them: pandoc for conversions, ripgrep for faster search, w3m or lynx for reading bookmarked pages in the terminal, and gpg or openssl for encryption.

The daily loop is four commands

The tool earns its keep through a handful of verbs that behave the same everywhere. nb add "Meeting notes" opens $EDITOR on a new file; nb 12 shows item 12; nb edit 12 opens it; nb search "postgres wal" greps across the notebook. Items are addressed by number, filename or title, and notebooks by name with a colon prefix, so nb work:search "invoice" searches only the work notebook. Tags are plain #hashtags in the text and nb list --tags finds them. A todo item is a Markdown checkbox, and nb todo lists them; a folder is a folder.

This addressing scheme is the thing to internalise. Once you trust that nb 12 will always be the same note until you delete it, you stop thinking about files at all.

Bookmarks and archiving are the underrated half

nb bookmark https://example.com/post fetches the page, stores the title and a text conversion alongside the URL, and lets you add a comment and tags. The bookmark is a Markdown file like everything else, which means it is searchable offline and versioned with the rest. nb browse starts a local web view for reading and light editing, but it is a convenience on the same machine rather than a hosted service, and I would not expose it. For a shared, browser-first bookmark manager look at the bookmarks category; nb is for the person who wants the archive in the same repo as their notes.

Encryption works but changes the rules

nb add --encrypt (or nb add -e) writes a note encrypted with GPG or a passphrase through OpenSSL, and it decrypts on read with a password prompt. Two consequences matter. Encrypted notes are opaque to nb search, so a note you might need to find by content should not be encrypted. And the encrypted blob is still committed to Git, which is fine for the remote (that is the point) but means every edit produces a new unrelated blob and no useful diff history. I keep a small number of encrypted items (recovery codes, licence keys) and leave the remaining 95 percent in the clear on a remote I control.

What nb is not

It has no graphical client and no official mobile app. On a phone the practical workarounds are a Git client that edits Markdown, or Termux on Android with nb installed, and neither is pleasant. It also does not do rich text, embedded images in a preview, or a knowledge graph; if backlinks and canvas views are what you want, the comparison in notes apps you own covers the tools built around them. nb's AGPL-3.0 licence is irrelevant to almost everyone since you are not distributing a service.

What I'd do

Install nb on every machine you type on, create one notebook per life area, and give each a private remote on your own Forgejo with auto_sync on. Keep notes as plain Markdown, use #tags rather than folders for anything cross-cutting, encrypt only what you would not want in a plain repo, and let Git be the backup and the history. If a week in you find yourself wishing for a phone app, that is your answer and Joplin is the move; if you do not notice its absence, you have found the notes tool you will still be using in ten years.