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.
Every collection of notes in nb lives inside a notebook — a directory that is also a git repository. You can have as many notebooks as you like, switch between them with a single command, keep some local to a directory, and sync each one independently to a remote git host. The nb notebooks command (also available as nb n or nb nb) manages the full lifecycle of every notebook.
Full Usage
nb notebooks [<name> | <query>] [--ar | --archived] [--global] [--local]
[--names] [--paths] [--unar | --unarchived]
nb notebooks add ([<name>] [<remote-url> [<branch>... | --all]]) [--author]
[--email <email>] [--name <name>]
nb notebooks (archive | open | peek | status | unarchive) [<name>]
nb notebooks author [<name> | <path>] [--email <email>] [--name <name>]
nb notebooks current [--path | --selected | --filename [<filename>]]
[--global | --local]
nb notebooks delete <name> [-f | --force]
nb notebooks (export <name> [<path>] | import <path>)
nb notebooks init [<path> [<remote-url> [<branch>]]] [--author]
[--email <email>] [--name <name>]
nb notebooks rename <old-name> <new-name>
nb notebooks select <selector>
nb notebooks show (<name> | <path> | <selector>) [--ar | --archived]
[--escaped | --name | --path | --filename [<filename>]]
nb notebooks use <name>
nb n, nb nb
Listing Notebooks
Running nb notebooks with no arguments lists all global notebooks:
# List all notebooks
nb notebooks
# List only archived notebooks
nb notebooks --archived
nb notebooks --ar
# List only unarchived notebooks
nb notebooks --unarchived
nb notebooks --unar
# Print only notebook names (one per line)
nb notebooks --names
# Print full filesystem paths
nb notebooks --paths
# Filter notebooks by name or query
nb notebooks work
nb notebooks add — Create a Notebook
Create a new global notebook, optionally cloning it from a remote git URL:
nb notebooks add ([<name>] [<remote-url> [<branch>... | --all]]) [--author]
[--email <email>] [--name <name>]
# Create a new empty notebook named "sample"
nb notebooks add sample
# Create a notebook by cloning a remote repository
nb notebooks add example https://github.com/example/example.git
# Clone a specific branch
nb notebooks add example https://github.com/example/example.git main
# Clone all branches as separate notebooks
nb notebooks add example https://github.com/example/example.git --all
# Set the commit author during creation
nb notebooks add sample --author --email "me@example.com" --name "My Name"
nb notebooks create, nb notebooks new
nb notebooks use — Switch Notebooks
Set the active notebook for the current session. This is the most common way to change your working context. The top-level nb use command is a shortcut for nb notebooks use:
# Switch to the "work" notebook
nb notebooks use work
# Equivalent shortcut
nb use work
# Shortcut alias
nb u work
You don’t need to switch notebooks to operate on items in another one. Use
the <notebook>: selector prefix with any command:
nb work:add -t "New Note".
nb notebooks current — Show the Active Notebook
nb notebooks current [--path | --selected | --filename [<filename>]]
[--global | --local]
# Print the current notebook name
nb notebooks current
# Print the full path to the current notebook
nb notebooks current --path
# Print the name of the globally set notebook
nb notebooks current --global
# Check whether a local notebook is active (exit 0 = yes)
nb notebooks current --local
# Print an available filename for the current notebook
nb notebooks current --filename example.md
nb notebooks archive / nb notebooks unarchive — Archive Status
Archiving a notebook hides it from default listings and excludes it from cross-notebook search (nb search --all) while keeping all its data intact. The top-level nb archive and nb unarchive commands are aliases:
nb notebooks (archive | unarchive) [<name>]
# Archive the current notebook
nb archive
nb notebooks archive
# Archive a specific notebook by name
nb archive example
nb notebooks archive example
# Unarchive the current notebook
nb unarchive
nb notebooks unarchive
# Unarchive a specific notebook
nb unarchive example
nb ar (archive), nb unar (unarchive)
Set the git commit author name and email for a specific notebook, independently of the global git config:
nb notebooks author [<name> | <path>] [--email <email>] [--name <name>]
# Launch interactive prompts to set author for the current notebook
nb notebooks author
# Set non-interactively
nb notebooks author example --email "me@example.com" --name "My Name"
nb notebooks delete — Remove a Notebook
nb notebooks delete <name> [-f | --force]
# Delete a notebook (prompts for confirmation)
nb notebooks delete old-notebook
# Skip the confirmation prompt
nb notebooks delete old-notebook --force
Deleting a notebook removes the entire directory and its git history from
your local filesystem. This cannot be undone unless you have a remote or
backup copy.
nb notebooks rename — Rename a Notebook
nb notebooks rename <old-name> <new-name>
nb notebooks rename my-notes personal-notes
nb notebooks move, nb notebooks mv
nb notebooks init — Initialize a Local Notebook
Create a local notebook anchored to a specific directory on disk, rather than a global one stored in ~/.nb. When you cd into that directory, nb automatically uses the local notebook:
nb notebooks init [<path> [<remote-url> [<branch>]]] [--author]
[--email <email>] [--name <name>]
# Initialize the current directory as a local notebook
nb notebooks init
# Initialize a specific path
nb notebooks init /path/to/project/notes
# Initialize by cloning a remote
nb notebooks init /path/to/notes https://github.com/example/notes.git
nb init — Initialize the First Notebook
nb init is a top-level command that creates the initial “home” notebook and generates a configuration file at ~/.nbrc. It is normally only needed once, immediately after installing nb:
nb init [<remote-url> [<branch>]] [--author] [--email <email>] [--name <name>]
# Basic initialization
nb init
# Initialize by cloning an existing notebook from a remote
nb init https://github.com/example/example.git
# Clone a specific branch
nb init https://github.com/example/example.git example-branch
# Set commit author details during initialization
nb init --email "me@example.com" --name "My Name"
nb notebooks export / nb notebooks import
Export a notebook to a portable directory or import an existing local directory as a global notebook:
nb notebooks (export <name> [<path>] | import <path>)
# Export the "example" notebook to the current directory
nb notebooks export example
# Export to a specific path
nb notebooks export example ~/backups/example-notebook
# Import a local directory as a global notebook
nb notebooks import ~/projects/my-notes
nb notebooks show (<name> | <path> | <selector>) [--ar | --archived]
[--escaped | --name | --path | --filename [<filename>]]
# Print the name of a notebook given its path
nb notebooks show /path/to/notebook --name
# Check archival status (exit 0 = archived)
nb notebooks show example --archived
# Print an escaped name (spaces replaced)
nb notebooks show "My Notes" --escaped
# Print an available filename in the notebook
nb notebooks show example --filename report.md
nb notebooks select — Temporary Notebook Selection
Switch to a notebook for a single operation using a colon-prefixed selector. The selection is not persisted — it does not change the value returned by nb notebooks current:
nb notebooks select example:
nb notebooks select example:123
nb notebooks status — Print Archival Status
# Status of the current notebook
nb notebooks status
# Status of a named notebook
nb notebooks status example
Remote Sync Configuration
Each notebook can sync independently to a remote git repository. Use nb remote and nb sync to configure and trigger sync operations:
# Set the remote URL for the current notebook
nb remote set https://github.com/example/notes.git
# Set remote with a specific branch
nb remote set https://github.com/example/notes.git my-branch
# Print the current remote
nb remote
# Sync the current notebook with its remote
nb sync
# Sync all unarchived notebooks
nb sync --all
When nb set auto_sync is enabled (the default), operations like add,
edit, and delete automatically commit and push changes to the configured
remote after each modification.
Common Workflow Examples
Create a dedicated work notebook
nb notebooks add work
nb use work
Connect it to a private remote repository
nb remote set https://github.com/yourname/work-notes.git
Add notes and let auto-sync push them
nb add --title "Q1 Planning"
# nb automatically commits and pushes
Archive the notebook when the project ends
Unarchive it later if you need to refer back