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 stores every note as a plain file inside a Git-tracked directory, so your data is always portable and never locked in a proprietary format. Notes are Markdown by default, but you can use any file type you like — from Org and LaTeX to JavaScript snippets and AsciiDoc documents. All the standard operations — adding, listing, editing, viewing, and deleting — are available from a single, consistent command-line interface that works the same way whether you are using a local notebook or syncing to a remote.

​
Adding Notes

Use nb add (shortcuts: nb a, nb +) to create new notes. With no arguments, nb add opens a blank file in your $EDITOR. Pass a string to create a note immediately without opening the editor. 
# open a blank note in your editor
nb add

# create a note with inline content (no editor)
nb add "This is a quick note."

# pipe content into a new note
echo "Note content." | nb add

# create a note in the notebook named "example"
nb example:add "This is a note."

# create a note inside the folder named "sample"
nb add sample/

​
Titles, Content, and Filenames

The --title (-t) option sets the note title and derives the filename from it automatically: 
# title becomes the filename: example_title.md
nb add --title "Example Title" "Example content."

# explicitly set filename, title, and content together
nb add --filename "example.md" -t "Example Title" -c "Example content."
Use --content (-c) to supply content inline, and combine it with piped input and a title argument for multi-source notes: 
pb | nb add "Argument content." \
    --title   "Sample Title"    \
    --tags    tag1,tag2         \
    --content "Option content."

​
Tags

Add #hashtags with --tags <tag1>,<tag2>.... Tags are inserted between the title and body: 
nb add "Example content." --title "Tagged Note" --tags tag1,tag2
The resulting file looks like: 
# Tagged Note

#tag1 #tag2

Example content.

​
File Types

nb defaults to .md (Markdown). Change the type with a filename extension, a bare extension, or --type: 
# open a new Org file
nb add example.org

# open a new reStructuredText file
nb add --type rst

# open a new JavaScript file
nb add .js

# save clipboard contents as a Rust file in the "rust" notebook
pb | nb a rust: .rs

​
Encryption

Pass --encrypt (-e) to create a password-protected note encrypted with AES-256 (OpenSSL) or GPG: 
nb add --title "Secret Document" --encrypt
Each encrypted note has its own password. nb prompts for the password transparently whenever the note is viewed or edited, then re-encrypts it automatically after editing.

​
Templates

Base a new note on a template string or file with --template: 
# template from a file
nb add --template /path/to/example/template

# template as an inline string
nb add --template "{{title}} • {{content}}"
Supported template tags: {{title}}, {{tags}}, {{content}}, {{date}} (and date format options such as {{date +"%Y-%m-%d"}}). Set a default template in ~/.nbrc: 
export NB_DEFAULT_TEMPLATE="/path/to/example/template"
Use nb add --no-template to skip the default template for a single command.

​
Shortcut Aliases

CommandAliases
nb addnb a, nb +, nb create, nb new

​
Listing and Filtering Notes

Run nb or nb ls to list notes in the current notebook. The notebook header appears above the list and a helpful footer with example commands appears below. 
nb
# home
# ----
# [3] Example Title
# [2] Sample Title
# [1] Demo Title
Notes are listed by most recently modified first. When a note has a Markdown # h1 title, YAML front matter title: field, or an Org/LaTeX/AsciiDoc title declaration, that title is shown instead of the filename.

​
Filtering by Title or Filename

Pass a string to filter the list. Single words fuzzy-match; quoted phrases match exactly; multiple words act as an OR filter: 
# fuzzy match
nb exa          # → [3] Example Title

# OR filter (any word matches)
nb example demo # → [3] Example Title, [1] Demo Title

# exact phrase match
nb "example title" # → [3] Example Title

​
Filter by Tags

Escape or quote the # when filtering by hashtag, or use --tags: 
# list items tagged with #tag1
nb \#tag1

# list items tagged with #tag2 in the "example" notebook
nb example: "#tag2"

# list items tagged with both #tag1 AND #tag2
nb \#tag1 "#tag2"

# using the --tags option
nb --tags tag2,tag3

​
Excerpts, Sorting, and Limits

# show a default-length excerpt for item 3
nb ls 3 --excerpt

# show an 8-line excerpt
nb ls 3 -e 8
Short options can be combined. nb -sre 2 is equivalent to nb --sort --reverse --excerpt 2.

​
Filter by Type

# list only bookmarks
nb --type bookmark
nb --bookmark

# list only todos
nb --type todo
nb --todo

​
nb list vs nb ls

nb ls combines the notebook header with a limited list (default 15 items). nb list shows only notes — no notebook header — and has no default limit: 
nb list
# [100] Example One Hundred
# [99]  Example Ninety-Nine
# ...

​
Editing Notes

Open a note in $EDITOR with nb edit (shortcut: nb e). You can identify notes by id, filename, or title: 
# edit by id
nb edit 3

# edit by filename
nb edit example.md

# edit by title
nb edit "A Document Title"

# edit the last modified item
nb edit --last
nb edit -l
The identifier and subcommand can also be reversed: nb 3 edit or nb example:12 e.

​
Appending, Prepending, and Overwriting

When content is supplied via --content or pipe, nb edit appends without opening the editor: 
# append content
echo "Content to append." | nb edit 1
nb edit 1 --content "Content to append."

# overwrite existing content
nb edit 1 --content "Replacement content." --overwrite

# prepend before existing content
nb edit 1 --content "Prepended content." --prepend
Add --edit to any of the above to still open the editor before committing.
When a note is encrypted, nb edit decrypts it in a temporary file, opens your editor, then re-encrypts the note automatically when you save and quit.

​
Viewing Notes

Use nb show (shortcut: nb s) to view a note. By default, notes open in less with syntax highlighting (if bat, highlight, or Pygments is installed): 
nb show 3
nb show example.md
nb show "A Document Title"

# alternative syntax
nb 3 show
nb example:12 show

​
Output Options

# print to stdout with syntax highlighting
nb show 123 --print

# print without syntax highlighting
nb show 123 --print --no-color

# render as HTML and open in terminal browser (requires Pandoc)
nb show example.md --render

​
Getting Metadata

# date added
nb show 2 --added

# date last updated
nb show 2 --updated
Use nb open to open a note in your system’s preferred GUI application. Use nb browse to view rendered notes in a terminal or GUI web browser with clickable links and tag navigation.

​
Deleting Notes

Pass any number of ids, filenames, or titles to nb delete (shortcuts: nb d, nb -). A confirmation prompt is shown by default: 
# delete by id
nb delete 3

# delete by filename
nb delete example.md

# delete multiple items at once
nb delete 89 56 21

# delete an item in a notebook
nb delete example:12

# skip confirmation prompt
nb delete 3 --force

​
Moving and Renaming Notes

Use nb move (aliases: nb rename, nb mv) to move or rename a note: 
# rename by changing extension
nb move example.md sample.org

# rename note 2 to a new name
nb rename 2 "New Name"

# move note 12 from "example" notebook into a folder in "demo" notebook
nb move example:12 demo:Sample\ Folder/

# change only the file extension
nb rename 5 .org

# rename to match the note's title
nb rename 12 --to-title

# convert a note to a bookmark
nb rename 3 --to-bookmark

# convert a bookmark back to a note
nb rename 6 --to-note

# convert a note to a todo
nb rename 7 --to-todo

# reset the filename to the last-modified timestamp
nb rename 8 --reset

​
Copying Notes

Use nb copy (alias: nb duplicate) to copy a note to a new location or duplicate it in place: 
# copy item 456 to "sample.md"
nb copy 456 sample.md

# copy item 678 to the "example" notebook
nb copy 678 example:

# copy item 789 to the "demo" folder
nb copy 789 demo/

# duplicate in place (nb assigns a new filename automatically)
nb copy 123

​
Quick Reference

Add

nb add, nb a, nb +, nb create, nb new

Edit

nb edit, nb e

Show

nb show, nb s, nb view

Delete

nb delete, nb d, nb -

Build docs developers (and LLMs) love

Get started for freeTalk to us