nb

name

nb

description

Reference skill for nb (https://xwmx.github.io/nb/), a CLI note-taking, bookmarking, archiving, and knowledge base tool. Use when working with nb commands, notebooks, notes, bookmarks, todos, tasks, tagging, linking, search, folders, git sync, import/export, browsing, selectors, metadata, or any nb-related operation. Prefer nb native commands over custom reimplementations — check this skill before building new functionality. Triggers on: nb commands, notebook management, note creation/editing, bookmarking, todo management, tagging, wiki-style linking, searching notes, git-backed sync, pandoc conversion, encrypted notes, zettelkasten, or any question about nb capabilities.

nb — Command Reference for Agents

Principle: native over custom. Before implementing any note/bookmark/search/sync feature, check if nb already does it natively.

Quick Command Reference

Action	Command	Notes
Add note	nb add "content"	Also: nb a, nb +
Add with title	nb add -t "Title" "content"	Filename auto-derived from title
Add with tags	nb add --tags tag1,tag2 "content"	Stored as #tag1 #tag2
Add from pipe	echo "text" | nb add
Add from file	nb add example.md	Opens in editor
Add encrypted	nb add -t "Secret" --encrypt	AES-256 via OpenSSL or GPG
Add with template	nb add --template /path/to/tpl	Tags: {{title}} {{tags}} {{content}} {{date}}
Add in notebook	nb notebookname:add "content"	notebook: prefix
Add in folder	nb add foldername/ "content"
List notes	nb ls	Also: nb, nb list
List with excerpt	nb ls -e
List by type	nb ls --<type>	Types: note, bookmark, todo, etc.
List in folder	nb ls foldername/
Show note	nb show <id>	Also: nb s
Show raw	nb show <id> --print	No pager/rendering
Show title	nb show <id> --title
Show path	nb show <id> --path
Show filename	nb show <id> --filename
Show added date	nb show <id> --added
Show updated date	nb show <id> --updated
Edit note	nb edit <id>	Also: nb e
Edit with content	nb edit <id> -c "new content"	Non-interactive
Edit prepend	nb edit <id> --prepend -c "top text"	Prepend to existing
Edit overwrite	nb edit <id> --overwrite -c "full text"	Replace all content
Delete note	nb delete <id>	Also: nb d, nb -
Search	nb search <query>	Also: nb q
Search by tag	nb search --tag tagname	Also: nb q -t tagname
Search AND	nb q term1 --and term2
Search OR	nb q term1 --or term2
Search NOT	nb q term1 --not term2
Search in paths	nb search <query> --path	Print matching file paths
Bookmark URL	nb bookmark <url>	Also: nb bk, nb bm
Bookmark with tags	nb bookmark <url> -t tag1,tag2
Bookmark with quote	nb bookmark <url> -q "quote"
Bookmark with comment	nb bookmark <url> -c "comment"
Bookmark search	nb bookmark search <query>
Open bookmark	nb open <id>	Also: nb o
Peek bookmark	nb peek <id>	Also: nb p, terminal preview
Add todo	nb todo add "Title"
Todo with tasks	nb todo add "Title" --task "Task 1" --task "Task 2"
Todo with due date	nb todo add "Title" --due 2025-12-31
Mark task done	nb do <id> [task#]	Also: nb todo do
Undo task	nb undo <id> [task#]	Also: nb todo undo
List todos	nb todos	nb todos open / nb todos closed
List tasks	nb tasks	Across all todos
Pin item	nb pin <id>	Appears first in lists
Unpin	nb unpin <id>
Move item	nb move <id> <destination>	Also: nb mv
Copy item	nb copy <id> <destination>	Also: nb cp
Count items	nb count	In notebook or folder
Browse	nb browse	Terminal web UI, also: nb b
Browse GUI	nb browse --gui	Open in system browser

Notebooks

| Action | Command | | ------------------- | ----------------------------------- | ----------------- | | List notebooks | nb notebooks | | Add notebook | nb notebooks add <name> | | Add with remote | nb notebooks add <name> <git-url> | | Switch notebook | nb use <name> | | Show current | nb notebooks current | | Delete notebook | nb notebooks delete <name> | | Rename notebook | nb notebooks rename <old> <new> | | Archive | nb archive <name> | | Unarchive | nb unarchive <name> | | Notebook status | nb notebooks status <name> | | Scoped command | nb <name>:<subcommand> | e.g. nb work:ls | | Initialize | nb init [remote-url] |

Folders

Action	Command
Add folder	nb folders add <name>
Delete folder	nb folders delete <name>
List folders	nb folders

Git & Sync

Action	Command
Set remote	nb remote set <url> [branch]
Sync	nb sync
Sync all	nb sync -a
Git checkpoint	nb git checkpoint "msg"
Git dirty check	nb git dirty
Raw git	nb git <any-git-cmd>
History	nb history <id>
Status	nb status

Import / Export

Action	Command
Import file	nb import <path>
Import to notebook	nb import copy <path> -- notebook:<name>
Import from URL	nb import download <url>
Import bookmarks	nb import bookmarks <file>
Export note	nb export <id> <path>
Export via pandoc	nb export pandoc <id> [pandoc opts]
Export notebook	nb export notebook <name> <path>
Import notebook	nb notebooks import <path>

Linking & Zettelkasten

Wiki-style [[double bracket]] linking is built in:

# Create linked notes — use [[title]] syntax in content
nb add "See also [[related-note]]"

# Links are bidirectional — nb browse shows backlinks
nb browse

Selectors (:/) address items across notebooks:

nb show /path/to/notebook/folder/item
nb edit /home/wiki/example-note

Search Patterns

# Full-text search with regex
nb search "pattern"

# Search within a notebook
nb search example: "pattern"

# Search by type
nb search "pattern" --type bookmark

# Search tags specifically
nb search --tags              # list all tags
nb search --tag tagname       # items with tag

# Combine: AND, OR, NOT
nb q "term1" --and "term2" --not "term3"

Key Settings

nb set editor <editor>           # Default editor
nb set default_extension <ext>   # Default file extension
nb set color_theme <theme>       # Color theme
nb set encryption_tool <tool>    # openssl or gpg
nb settings list                 # View all settings

Alias Summary

Alias	Full Command
nb a / nb +	nb add
nb e	nb edit
nb s	nb show
nb d / nb -	nb delete
nb q	nb search
nb o	nb open
nb p	nb peek
nb b	nb browse
nb bk / nb bm	nb bookmark
nb mv	nb move
nb cp	nb copy

When to Use What

• Creating/reading/updating notes: Use nb add, nb show, nb edit
• Searching content: Use nb search / nb q — supports regex, tags, AND/OR/NOT
• Managing bookmarks: Use nb bookmark — downloads, cleans, caches page content
• Task management: Use nb todo add with --task items, nb do / nb undo
• Organizing: Use notebooks (nb notebooks), folders (nb folders), tags (--tags), pins (nb pin)
• Syncing: Use nb sync — git-backed, works with any git remote
• Importing files: Use nb import — supports pandoc conversion
• Browsing: Use nb browse — terminal or GUI web UI with rendered markdown

Detailed Reference

For complete command documentation with all flags and examples, read references/commands.md.

Updating This Skill

Run the update script to regenerate the reference from the installed nb version and online docs:

scripts/update_reference.sh

This scrapes nb help output and the nb README to keep the reference current.