nb

name	nb
description	Use when creating, listing, searching, bookmarking, or organizing notes with the nb CLI.
author	Benjamin Jesuiter <[e-mail]>
homepage	https://github.com/xwmx/nb
metadata	{"clawdbot":{"emoji":"📓","os":["darwin","linux"],"requires":{"bins":["nb"]}}}

nb - Command Line Note-Taking

⚠️ IMPORTANT: Never edit files in nb git repos (~/.nb/*) by hand! Always use the nb CLI to ensure proper indexing and Git commits.

A command line and local web note-taking, bookmarking, and archiving tool with plain text data storage, Git-backed versioning, and wiki-style linking.

Quick Reference

Notebooks

# List all notebooks
nb notebooks

# Switch to a notebook
nb use <notebook>

# Create a new notebook
nb notebooks add <name>

# Show current notebook
nb notebooks current

Adding Notes

# Add a note with title
nb add -t "Title" -c "Content here"

# Add note to specific notebook
nb <notebook>: add -t "Title" -c "Content"

# Add note with tags
nb add -t "Title" --tags tag1,tag2

# Add note from file content
nb add <notebook>:filename.md

Listing Notes

# List notes in current notebook
nb list

# List all notes (no limit)
nb list -a

# List notes in specific notebook
nb <notebook>: list

# List with excerpts
nb list -e

# List with tags shown
nb list --tags

Showing Notes

# Show note by ID or title
nb show <id>
nb show "<title>"

# Show note from specific notebook
nb show <notebook>:<id>

# Print content (for piping)
nb show <id> --print

Searching Notes

# Search across all notebooks
nb search "query"

# Search in specific notebook
nb <notebook>: search "query"

# Search with AND/OR/NOT
nb search "term1" --and "term2"
nb search "term1" --or "term2"
nb search "term1" --not "exclude"

# Search by tag
nb search --tag "tagname"

Editing Notes

# Edit by ID
nb edit <id>

# Edit by title
nb edit "<title>"

# Append content
nb edit <id> -c "New content to append"

# Prepend content
nb edit <id> -c "Content at top" --prepend

# Overwrite content
nb edit <id> -c "Replace all" --overwrite

Deleting Notes

# Delete by ID (will prompt)
nb delete <id>

# Force delete without prompt
nb delete <id> -f

Moving/Renaming

# Move note to another notebook
nb move <id> <notebook>:

# Rename a note
nb move <id> new-filename.md

Todos

# Add a todo
nb todo add "Task title"

# Add todo with due date
nb todo add "Task" --due "2026-01-15"

# List open todos
nb todos open

# List closed todos
nb todos closed

# Mark todo as done
nb todo do <id>

# Mark todo as not done
nb todo undo <id>

Bookmarks

# Add a bookmark
nb bookmark <url>

# Add with comment
nb bookmark <url> -c "My comment"

# Add with tags
nb bookmark <url> --tags reference,dev

# List bookmarks
nb bookmark list

# Search bookmarks
nb bookmark search "query"

Git Operations

# Sync with remote
nb sync

# Create checkpoint (commit)
nb git checkpoint "Message"

# Check dirty status
nb git dirty

# Run any git command
nb git status
nb git log --oneline -5

Folders

# Add folder to notebook
nb folders add <folder-name>

# List folders
nb folders

# Add note to folder
nb add <folder>/<filename>.md

Common Patterns

Adding Note with Full Content

For longer notes, create a temp file and import:

# Write content to temp file first, then copy to nb
cp /tmp/note.md ~/.nb/<notebook>/
cd ~/.nb/<notebook> && git add . && git commit -m "Add note"
nb <notebook>: index rebuild

Searching Across All

# Search everything
nb search "term" --all

# Search by type
nb search "term" --type bookmark
nb search "term" --type todo

Data Location

Notes are stored in ~/.nb/<notebook>/ as markdown files with Git versioning.

~/.nb/
├── notebook-name-1/ # Your first notebook
├── notebook-name-2/ # Your second notebook
└── ...

Tips

1. Use nb <notebook>: prefix to work with specific notebooks
2. IDs are numbers shown in nb list
3. Titles can be used instead of IDs (quoted if spaces)
4. All changes are automatically Git-committed
5. Use nb sync to push/pull from remote repos