Nb - Terminal Tooling

nb is a swiss army knife of a note taking tool operated entirely¹ in within the command line.

The nb command is your launch pad for everything note related. Without arguments nb shows you an overview of your existing notes or a quick cheat sheet of common actions if there are no notes.

Once you've created a few notes, nb (without arguments) instead displays all the notes in your current notebook (more on notebooks later)

nb allows for quick jotting down of notes, tasks, bookmarks. In addition, it provides the means of organizing your notes so you don't end up with a jumbled mess of random thoughts.

What follows will be a whirlwind tour of the major features mention with some practical examples.

The note. The foundational concept of any note taking system. A good system allows for quickly jotting down thoughts, organizing those thoughts into some system that aids in note retrieval, and (in my opinion) is flexible enough to be adapted to the user's individual preferences in format and structure.

nb excels in storing and retrieving notes, but it can handle todo items as well. For this, nb differentiates todos from tasks. A todo is a overall body of work to be done. In nb, a todo is stored in its own file and is visible from the list command.

To create a todo, you can use the todos sub command with the add argument.

nb todos add 'Finish this article'

Added: [5] ✔️  20231129140921.todo.md "[ ] Finish this article"

Calling nb todos without any arguments will list only the items of type todo.

A task is a single component of a todo. A todo can have many tasks. You can add tasks to a todo at creation time with the --task flag if you know what they will be up front.

nb todos add 'Learn about todos and tasks' --task 'learn about todos' --task 'learn about tasks' --task 'learn how to complete todos'

Added: [6] ✔️  20231129141554.todo.md "[ ] Learn about todos and tasks"

As you can see, only the top level todo is display in the list view. Using the tasks command will show us each todo and its associated tasks if it has any.

Todos can be checked off using nb todos do or nb do for an even shorter method.

Tasks can be checked off is the same way using the selector as it's displayed in the tasks view.

Unchecking a task is done with undo.

Internally, todos (and tasks) are just markdown files nb manages for you. You can look at them directly and even edit them by hand if you want. This can be helpful if you want to put more context into the todo.

And when running nb edit 6:³

Bookmarks are one more type of note-adjacent item you can store in nb. They are created by providing nb with a url. nb will store the url and scrape the website for its title and convert the content into markdow to store along with the link.

This is a great way both to keep track of a url for later, but also for distraction free, offline viewing of the site at some future date.

Technically the bookmark part of the above command is optional. When you give an argument that looks like a url to nb, it is aware and creates a bookmark for you. e.g. nb https://google.com would bookmark google.

As you can see, nb parsed the title of the website, and stored the url provided. If you tell nb to open the item (nb open 7), it will open the stored link in your web browser. show will open the parsed contents of the page in less, and edit allows you to, you guessed it, edit the contents of the converted page contents. Lastly, giving no additional arguments to the bookmarks command (bk for short) will show you only the bookmark items you have saved.

Notebooks are an organizational structure to silo some notes from others. When listing notes (or todos, bookmarks, etc.), only notes from the current notebook are displayed.

The screenshots you've seen so far crop out the notebook ui from the top center of its output.

Notebooks can be created with the notebook subcommand. nb notebook add sample would create a new notebook called sample. nb notebook delete sample would delete it.

The highlighted work indicates it is the current notebook, meaning all commands will function only on the items within this notebook. You can switch to a different notebook using the use command, but if you just want to run a one off search, view, or edit command, you can prefix the selector with the notebook name and a :.

In my understanding, notebooks make sense if you keep multiple logically unrelated corpora of notes.

nb also supports folders which act exactly as you would expect a folder to. Folders can be used to organize or hierarchically order your notes. In nb, they help to reduce clutter of your notes because any note inside a folder is not displayed by default.

Folders (unlike notebooks) will be created on the fly as needed given the path of the note you want to create. In this case, the folder my_folder was created dynamically in order to create the note.

You can view the contents of a folder by issuing the folder name and a /.

Pretty much every command can be prefixed with a selector, meaning you can put your bookmark in a different notebook, a todo inside a folder, a note inside a different notebook's nested folder, etc.

nb has intuitive and powerful search functionality, allowing you to search for strings, regexes, tags (covered briefly in this article, but you should check them out in full), types of notes, and combine all of the above with Boolean operators: --and and --or. The sub-command to search is search or q for short.

Searches are performed in the current notebook by default, but like any other nb command, can target any notebook and/or folder if desired.

Searches can be made across all of your notes using the -a flag.

I won't go much deeper into nb's search functionality, so you can check it out yourself if you're interested. It's very easy to figure out and follows intuitive conventions if you've used any searching tool before.

To get a feel for how searches work, here are a few examples taken from the docs:

# search current notebook for "example query"
nb search "example query"

# search the notebook "example" for "example query"
nb search example: "example query"

# search all unarchived notebooks for "example query" and list matching items
nb search "example query" --all --list

# search for "example" AND "demo"
nb search "example" "demo"

# search for "example" AND "demo"
nb search "example" --and "demo"

# search with regular expression
nb search "\d\d\d-\d\d\d\d"

# search for items tagged with "#tag1"
nb search --tags tag1

# search for items tagged with "#tag1" (short version)
nb q -t tag1

# search for items tagged with "#tag1" (even shorter version)
nb q "#tag1"

# search in the "example" notebook for "example"
nb example:q "example"

nb is busting at the seams with functionality. This article has covered maybe a quarter of all the things it can do. Their documentation is fantastic and covers everything I didn't have time to. Additionally the built in help is also comprehensive (nb help, or just throw a --help onto any command you're trying to work with). It also supports linking notes to each other (see docs), syncing notes automatically using a git repository, color themes, a robust plugin system, images, videos (nb import, docs), and more.

Despite the overwhelming breadth of features, I've found working with nb very pleasant to explore incrementally. Commands are well documented, arguments are flexible, meaning you don't have to memorize the exact order or name of every command; even if you're close, nb will likely understand what you were trying to do, and will do it for you.

I especially that you can specify your preferred file format; nb doesn't force you to use whichever format they decided is best; you get to choose.⁴

I also greatly appreciate that all your notes are stored on your filesystem, in a simple folder structure stored in ~/.nb.

In a world of cloud only, proprietary solutions, I find myself looking for simple solutions using existing and well known technologies with a preference for offline first. I want to be able to zip my notes and copy them to another computer, or better yet, utilize Dropbox or git to track and transfer changes. nb manages syncing behind the scenes for you using git if you provide a remote repository for it to sync with. This is the simplest solution to sync I have seen. If you're interested in more of the details of nb's sync functionality, see their docs on the concept.

Even refreshing note taking tools like obsidian which store your notes in plain markdown on your machine require a paid subscription for access to their sync functionality, while other tools silently migrate useful features from their free plans into their paid ones.

nb strikes a balance between the do-it-yourself freedom of note organization and the power that comes from enforcing a known format (todos, bookmarks, notebooks, etc.). The only "missing" feature I noticed was a lack of mobile support, but that hardly feels fair to fault a terminal note taking tool for missing. If that's a deal breaker, perhaps nb won't be the perfect tool for you.

It was easy enough to get started with nb and because the files are any format you like, stored on your computer, you risk nothing if you don't end up liking it, so I'd recommend just giving it a shot.