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.

Selectors are structured addresses used throughout nb to identify notebooks, folders, and items. Every nb subcommand that targets a specific item, folder, or notebook accepts a selector as its argument — from nb show and nb edit to nb move and nb delete. Mastering the selector syntax unlocks nb’s full composability.

​
Selector Syntax

A selector is constructed by combining an optional notebook name, an optional folder path, and an optional item identifier: 
[<notebook>:][<folder-path>/][<id> | <filename> | <title>]
All three components are optional, but at least one must be present. The full pattern looks like: 
notebook:folder/path/item-identifier
A complex real-world example: 
cli:tools/shellcheck/home-page.bookmark.md
This selector points to the file home-page.bookmark.md inside the tools/shellcheck/ folder path within the cli notebook.

​
Notebook Selectors

Notebooks are identified by their name followed by a colon (:). When the selector is only a notebook name and colon — with no folder path or item identifier — the command runs in the root folder of that notebook: 
# list items in the "example" notebook
nb example:

# add a new note named "Example Title" to the "example" notebook
nb add example: --title "Example Title"

# edit item with id "123" in the notebook "example"
nb edit example:123

​
Subcommand Selectors

A notebook selector can also be combined with a subcommand name to run the command within that notebook: 
# list all items in the "example" notebook and display excerpts
nb example:list -e

# edit item with id "123" in the "example" notebook
nb example:edit 123

# show the git history for the notebook named "example"
nb example:history
Subcommand selector examples: 
notebook:
notebook:show
notebook:history
notebook:a
notebook:q

​
Folder Selectors

Folders are identified by their relative path from the notebook root. A trailing slash signals that the command should operate on the contents of the folder. Without the trailing slash, the selector refers to the folder item itself: 
❯ nb list sample
[1] 📂 sample

❯ nb list sample/
[sample/3] Title Three
[sample/2] Title Two
[sample/1] Title One
Folder path segments can use either names or ids, and they can be mixed freely: 
# list items in "sample/demo/"
nb sample/demo/

# add a new item to the folder named "demo" inside the folder with id "3"
nb add 3/demo/

# show history for folder id "4" inside "sample/" in the "example" notebook
nb history example:sample/4/
Use a trailing slash (folder/) to address folder contents, and omit it to address the folder item itself.

​
Item Selectors

Items can be identified by numeric id, filename, or title — optionally preceded by a notebook name and/or folder path.

​
By ID

# edit item with id "123"
nb edit 123

# show item with id "123" in the "example" notebook
nb show example:123

# show item with id "123" in the "folder/" of "example"
nb show example:folder/123

​
By Filename

# show a file by name in the current notebook
nb show example.md

# show a file by name in the "example" notebook
nb show notebook:example.md

​
By Title

# open an item by title in the current notebook
nb open "Example Title"

# open an item by title in the "example" notebook
nb open notebook:"Example Title"

# open the item titled "demo title" in the folder with id "3"
nb open 3/demo\ title

​
By Full Path

Items can also be addressed using their absolute filesystem path: 
# edit "demo.md" in the "sample" folder in the "home" notebook
nb edit /home/example/.nb/home/sample/demo.md

​
Identifier Selector Reference

The following summarizes all valid identifier selector forms: 
123
example.md
title
relative/path/to/123
relative/path/to/demo.md
relative/path/to/title
/full/path/to/sample.md
notebook:123
notebook:example.md
notebook:title
notebook:relative/path/to/123
notebook:relative/path/to/demo.md
notebook:relative/path/to/title
Folder and item identifiers without a notebook name refer to items within the current notebook.

​
Mixing Names and IDs in Paths

Path segments can mix names and numeric ids at any level of nesting: 
# reference folder by id "3" then folder named "demo"
nb add 3/demo/

# reference "sample" by name then folder by id "4" inside "example" notebook
nb history example:sample/4/

​
Quick Reference

Notebook selector

example: — targets root of example notebook

Subcommand selector

example:list — runs list inside example notebook

Folder contents

folder/path/ — trailing slash targets folder contents

Folder item

folder/path — no trailing slash targets the folder itself

Item by id

example:folder/123 — item id 123 in folder of example

Full path

/home/user/.nb/home/sample/demo.md — absolute path

Build docs developers (and LLMs) love

Get started for freeTalk to us