xwmx/nb: a single shell script for plain text notes, bookmarks and archives

What nb is for, and who ends up using it

nb targets a specific kind of person: someone who already keeps a terminal open, already uses Git, and is tired of note applications that store data in a database they cannot read with cat. The README describes it as a command line and local web note-taking, bookmarking, archiving and knowledge base application, with plain text data storage as the first item in that list. That ordering is the whole pitch. Notes are files. You can open them in Vim, Emacs, VS Code, Sublime Text or any other editor, and nothing about the format depends on nb continuing to exist.

The bookmarking side is less common in this category. nb downloads page information, cleans it up, structures it and saves it as Markdown, so a saved link becomes an ordinary note you can edit. That matters for people who accumulate references and want them searchable offline rather than trapped in a browser profile. The project also looks up Internet Archive Wayback Machine snapshots for broken links, which is a small feature that says a lot about the intended audience: people who care whether a citation still resolves in five years.

It is not aimed at someone who wants a phone app that syncs automatically, or at a team that needs shared permissions and comments. Those users will find the tool's assumptions working against them.

One script, Git underneath, and progressive enhancement

The entire program is contained in a single shell script. The repository confirms this at the top level, where nb sits alongside nb.go/, nb.ksh/ and nb.zsh/ directories and a bin/ folder. The README calls the approach progressive enhancement: nb checks the environment for optional tools and uses them when they are available. bat, ncat or socat, pandoc, ripgrep, tig and w3m are listed as recommended, with a longer list of supported extras including asciidoctor, The Silver Searcher, catimg, Chafa, Chromium and Chrome.

That design has a direct consequence. Behaviour changes with the machine. Search may use ripgrep on one host and a slower fallback on another. Conversion requires pandoc, and the README does not promise a substitute. The same notebook, moved to a minimal container, will not behave identically.

Git is the second structural decision. nb uses Git in the background to record changes and sync notebooks with remote repositories, and the README notes it can also be configured to sync through a general purpose utility like Dropbox so notes can be edited in other apps. Versioning is therefore not a feature bolted on later; it is the storage model. Every edit is a commit, which is excellent for history and awkward if you wanted a flat file tree with no repository attached.

Installing nb and creating a first note

Required dependencies are Bash, Git and a text editor with command line support. Bash must be present on the system even if your login shell is Zsh or fish. The Makefile installs the nb script and the bookmark helper into PREFIX, which defaults to /usr/local, and then calls nb env install:

make install

With PREFIX unset, that places nb and bookmark in /usr/local/bin and runs nb env install as part of the same target. The package.json records the install command as make install, so the two agree. To reverse it, make uninstall removes both binaries and calls nb env uninstall.

The README's own install instructions are not reproduced in full here; the repository also ships package.sh, which is the entry point the project's documentation points to for the curl-style installation. If you prefer not to install system-wide, the script is designed to be copied or curl'ed almost anywhere and just work.

Once nb is on PATH, create a note. The README does not quote a first-run command in the excerpt available, so the safe move is to check the environment first:

nb env

That reports which optional tools nb can see. Then open a new note with your configured editor:

nb add

The result should be a new file inside the default notebook directory, with a Git commit recorded behind it. Run nb list afterward to confirm the note appears in the listing. If you want to see the notebook's location and settings, nb env is again the place to look.

Where nb gets awkward

The single-script design is the source of both its portability and its sharpest edges. Anything that depends on an external binary silently loses capability when that binary is missing. Pandoc-backed import and export is the clearest case: without pandoc installed, conversion is not available, and nothing in the README's dependency section suggests nb will prompt you or fail loudly. You have to know to check.

Git as the storage layer is a second trade-off. Every note operation touches a repository, which means merge conflicts are a real category of problem when two machines edit the same notebook. The README describes syncing with remote repositories and with Dropbox-style utilities, but it does not document a conflict resolution workflow. Users who expect a sync service to merge silently will be surprised.

There is also a platform boundary. nb works in any standard Linux or Unix environment, including macOS and Windows via WSL, MSYS and Cygwin. Native Windows is not in that list. And the AGPL-3.0 licence is worth reading before you embed nb in something you distribute; the package.json records it as AGPL-3.0-or-later, which is a stronger copyleft position than the MIT licence typical of CLI note tools.

nb against a plain Git repository of Markdown files

The honest alternative for many readers is not another note application. It is a directory of Markdown files, a Git remote, and a handful of shell aliases. That setup has no dependencies beyond Git and your editor, and nothing to upgrade.

The difference is what nb adds on top of the same substrate. It provides filtering, pinning, tagging, wiki-style linking, todos with tasks, global and local notebooks, folders, colour themes and plugins, all against the same plain files. Search covers cached bookmark content with regular expression support, which a bare grep over your notes will not do because the page content has to be fetched and cleaned first. The local web interface, served for terminal and GUI browsers, is another layer with no equivalent in a raw repository.

So the comparison is not about data format. Both approaches end with text files under version control. It is about how much tooling you want between you and those files. If you would rather write the aliases yourself and keep the dependency count at one, nb is unnecessary. If you want tagging, linking and bookmark archiving to work the same way on every machine you use, the script is doing real work.

Maintenance, releases and the licence question

The last push to master was on 2026-08-26, and the most recent release is 7.25.5 from 2026-08-12. The release cadence over the visible window is uneven: 7.25.4 landed on 2026-04-28 and 7.25.3 on 2026-03-16. Three releases in roughly five months, with the newest arriving shortly before the last commit. The repository is not archived.

Upgrade cost is low by construction. Because nb is one script, updating means replacing a file, and the Makefile's install target is the same command you ran the first time. There is no dependency tree to reconcile and no package-lock churn to review, even though package.json and package-lock.json exist in the repository. The risk sits on the other side: a single file means a single point of failure, and a bad release cannot be pinned by version range the way a library dependency can. Keeping a copy of the previous script is the practical rollback, and the README does not document a rollback mechanism.

On licensing, nb is AGPL-3.0-or-later per package.json. For individual use this changes nothing. If you plan to modify nb and offer it to others over a network, the AGPL's source-availability terms are relevant, and that is a question for a lawyer rather than for this article.

Editorial conclusion

Adopt nb if you want notes as plain files in a Git repository and you are comfortable in a terminal; skip it if you need a hosted sync service, a mobile client or a graphical editor out of the box. Before committing, verify that Bash, Git and a command-line editor are present, run nb env install after make install, and confirm the Pandoc and ripgrep binaries you expect are actually on PATH, because nb degrades quietly without them.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. xwmx/nb on GitHub