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 has a first-class plugin system built directly on the CLI itself. Plugins are plain Bash scripts with a .nb-plugin extension that can define new subcommands, add functionality, and interact with every nb feature using the same internal functions that nb uses internally. Because the API is just the CLI — accessed through underscore-prefixed function names — plugins are composable, portable, and easy to write.

​
How the API Works

The nb API is the command line interface itself. Within plugins, every nb subcommand is available as a Bash function named with a leading underscore (_): 
# call "nb show" from inside a plugin
_show 3 --print --no-color

# call "nb notebooks" from inside a plugin
_notebooks --names --no-color --unarchived --global

# call "nb list" from inside a plugin
_list --filenames --no-id --no-indicator

# call "nb notebooks current" from inside a plugin
_notebooks current --path
nb also automatically scans all arguments for selectors containing notebook names and updates the current notebook context when a valid one is found, so your plugin inherits the same selector resolution as built-in subcommands.

​
Plugin File Structure

Plugins are Bash-compatible shell scripts with a .nb-plugin file extension. A minimal plugin is created in three steps.
1

Register the subcommand name

Use _subcommands add to declare the new subcommand:
_subcommands add "example"
2

Define help and usage text

Use _subcommands describe with a heredoc to provide help text shown by nb help example:
_subcommands describe "example" <<HEREDOC
Usage:
  nb example

Description:
  Print "Hello, World!"
HEREDOC
3

Define the subcommand function

Write a Bash function named with a leading underscore matching the subcommand name:
_example() {
  printf "Hello, World!\n"
}
That’s a complete, working plugin. With it installed, nb example prints Hello, World!.

​
Core API Functions

​
_show — Query Item Information

_show <selector> [options] retrieves information about a specific item identified by a selector. The output format is controlled by option flags: 
_show "${_selector}" --filename

​
_notebooks — Notebook Information

# print the path to the current notebook
_notebooks current --path

# list all unarchived global notebook names (no color)
_notebooks --names --no-color --unarchived --global

​
_list — List Items

# list all filenames in the current notebook
_list --filenames --no-id --no-indicator

​
Other Subcommands

Any nb subcommand is accessible via its underscore-prefixed function name: 
_add     # nb add
_edit    # nb edit
_delete  # nb delete
_search  # nb search
_move    # nb move
_copy    # nb copy

​
Resolving Selectors to File Paths

A common pattern in plugins is accepting a selector argument and resolving it to a filename and notebook path so you can operate on the actual file: 
_example() {
  local _selector="${1:-}"
  [[ -z "${_selector:-}" ]] && printf "Usage: example <selector>\n" && exit 1

  # Resolve the selector to a filename
  local _filename=
  _filename="$(_show "${_selector}" --filename)"

  # Get the path to the current notebook
  local _notebook_path=
  _notebook_path="$(_notebooks current --path)"

  # Now operate on the file directly
  cat "${_notebook_path}/${_filename}"
}
This pattern — _show <selector> --filename paired with _notebooks current --path — is the standard way to bridge selector-based addressing and direct filesystem access within a plugin.

​
Subcommand Aliases

Plugins can also register command aliases using _subcommands alias: 
# register "ex" as an alias for "example"
_subcommands alias "example" "ex"

​
Complete Minimal Plugin Example

# Register the subcommand
_subcommands add "example"

# Describe the subcommand (shown by "nb help example")
_subcommands describe "example" <<HEREDOC
Usage:
  nb example

Description:
  Print "Hello, World!"
HEREDOC

# Define the subcommand function
_example() {
  printf "Hello, World!\n"
}

​
Installing Plugins

# install from a raw URL
nb plugins install https://raw.githubusercontent.com/xwmx/nb/master/plugins/clip.nb-plugin

# nb also accepts standard GitHub URLs
nb plugins install https://github.com/xwmx/nb/blob/master/plugins/example.nb-plugin
Installed plugins live in ${NB_DIR}/.plugins/ and are listed with nb plugins: 
❯ nb plugins
clip.nb-plugin
example.nb-plugin
turquoise.nb-theme

❯ nb plugins --paths
/home/example/.nb/.plugins/clip.nb-plugin
/home/example/.nb/.plugins/example.nb-plugin
/home/example/.nb/.plugins/turquoise.nb-theme
To uninstall: 
nb plugins uninstall example.nb-plugin

​
Example Plugins to Study

example.nb-plugin

The minimal reference plugin — a great starting point for writing your own.

clip.nb-plugin

Adds clipboard functionality, demonstrating _show, _notebooks current --path, and selector resolution.

ebook.nb-plugin

A full-featured plugin showing how to orchestrate multiple nb subcommands in a complex workflow.
Publish your plugin on GitHub, GitLab, or any public host — users can install it directly from the URL with nb plugins install <url>.

Build docs developers (and LLMs) love

Get started for freeTalk to us