Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xwmx/nb/llms.txt

Use this file to discover all available pages before exploring further.

nb is designed to feel natural from the first command. The interface is consistent across every operation — add, list, edit, show, search — and most commands have short aliases so common tasks stay fast. This guide walks you through everything you need to go from zero to productive in a single session.
1

Install nb

The quickest way to get nb running is via Homebrew on macOS or npm everywhere else:
# macOS
brew install xwmx/taps/nb

# npm (Linux, Windows WSL, and others)
npm install -g nb.sh
For additional methods including curl, wget, and make, see the Installation guide.
2

Run nb for the first time

Simply run nb with no arguments:
nb
On first run, nb creates your home notebook at ~/.nb/home/ and initializes it as a Git repository. From that point on, every change you make is automatically committed to local version history.
home
----
0 notes.
Add a note:
  nb add
TIP: Use `nb help` to see all subcommands.
Notebooks and notes are global by default — they live at ~/.nb and are accessible from any working directory.
3

Add your first note

Use nb add (shortcut: nb a) to create notes in several ways:
# Open a new blank note in your text editor
nb add

# Create a note instantly from a string (no editor opened)
nb add "This is my first note."

# Create a note with a title
nb add --title "Meeting Notes"

# Create a note with a title and content
nb add --title "Ideas" --content "Write down everything."
When you add a note with content, nb confirms immediately:
Added: [1] 20200101000000.md
You can also pipe content directly into nb add:
echo "Note content." | nb add
4

List your notes

Running nb or nb ls lists everything in the current notebook:
nb
# or
nb ls

home
----
[3] Example Title
[2] Sample Title
[1] Demo Title
Each note is shown with its id, filename (or title when one is defined), and a content excerpt. Notes are listed in order of last modification.
5

Edit a note

Use nb edit (shortcut: nb e) followed by an id, filename, or title:
# Edit note with id 1
nb edit 1

# Same using the shortcut alias
nb e 1

# Edit by filename
nb e example.md

# Edit by title
nb e "Meeting Notes"
nb opens the note in your $EDITOR. After you save and close, the change is automatically committed to Git.
6

View a note

Use nb show (shortcut: nb s) to inspect a note:
# Open note 1 in the pager
nb show 1

# Print note 1 directly to the terminal
nb show 1 --print

# Using the shortcut alias
nb s 1
nb show renders Markdown with syntax highlighting when bat or another supported viewer is installed.
7

Search your notes

Use nb search (shortcut: nb q) to run a full-text search across all notes and cached bookmark content:
# Search for a phrase
nb search "example query"

# Using the shortcut alias
nb q "example query"
Example output:
[3] example.md "Example Title"
---------------------------------
3: Example content with example query inside.
You can also search by tag:
# Search for items tagged with #tag1
nb q --tag tag1

# Using a hashtag argument directly
nb q \#tag1
8

Save a bookmark

Pass any URL as the first argument to nb to create a bookmark:
nb https://example.com
nb fetches the page, extracts the title, description, and content, and saves everything as a structured Markdown file:
# Example Title (example.com)

<https://example.com>

## Description

Example description.

## Content

Example Title
=============

This domain is for use in illustrative examples...
The cached content is indexed for full-text search with nb q, viewable in a local browser with nb browse, and readable in any text editor like any other note.
9

Sync with a Git remote

To back up or sync your notebook across machines, add a remote and sync:
# Add a remote to the current notebook
nb remote set https://github.com/example/notes.git

# Sync (push and pull) the current notebook
nb sync
nb automatically commits every change, so nb sync just pushes local commits and pulls any remote changes. Enable automatic syncing with:
nb set auto_sync 1

​
Shortcut Aliases Reference

nb provides short aliases for the most common commands. Once you learn them, day-to-day note-taking becomes a single keystroke:
ShortcutFull commandWhat it does
nb anb addAdd a new note or file
nb enb editEdit a note in $EDITOR
nb snb showView / print a note
nb dnb deleteDelete a note
nb qnb searchFull-text search
nb bnb browseBrowse in web interface
nb onb openOpen bookmarked URL in browser
nb pnb peekPreview bookmarked URL in terminal browser
Run nb help for a full command listing, or nb help <subcommand> — for example nb help add — for detailed options on any specific command.

​
What’s Next

Notes

Deep-dive into creating, organizing, tagging, linking, and managing notes with all available options.

Bookmarks

Learn how to save, annotate, search, and browse bookmarks including encrypted and tagged collections.

Reference Overview

Complete reference for every nb subcommand, flag, and selector syntax.

Configuration

Customize nb with settings for your editor, default format, color theme, sync behavior, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us