nb Environment Variables and Configuration Reference

nb is configured entirely through environment variables, most of which live in the ~/.nbrc configuration file. Every variable can be set either by exporting it in your shell profile or by assigning it directly in ~/.nbrc, which you can open for editing with nb settings edit. This page is a complete reference for every supported variable, grouped by category.

Setting Variables

Variables are set in ~/.nbrc using standard shell assignment with export:

export NB_INDICATOR_PINNED="🔮"
export NB_DEFAULT_EXTENSION="org"
export NB_LIMIT="auto^15"

You can also configure them interactively through nb set / nb settings.

Editor

EDITOR

string

The terminal editor command used for editing items throughout the system. Used by nb unless overridden by $NB_EDITOR.Example values: code, emacs, hx, vim

NB_EDITOR

string

default:"value of $EDITOR"

The terminal editor command for editing items within nb specifically. Overrides $EDITOR in the environment.Example values: code, emacs, hx, vim

ACE Editor (Browse)

These variables configure the ACE editor used in nb browse for in-browser editing.

NB_ACE_ENABLED

string

default:"0"

Enable the ACE editor in nb browse. Set to 1 to enable.Supported values: 0, 1

NB_ACE_MD_GUTTER

string

default:"1"

Show the Markdown gutter in the ACE editor. Set to 0 to hide.Supported values: 0, 1

NB_ACE_RELATIVE_LINE_NUMBERS

string

default:"0"

Enable relative line numbers in the ACE editor. Set to 1 to enable.Supported values: 0, 1

NB_ACE_SOFT_TABS

string

default:"0"

Use soft tabs (spaces) instead of hard tabs in the ACE editor. Set to 1 to enable.Supported values: 0, 1

NB_ACE_KEYBOARD

string

default:"ace"

The keyboard binding mode for the ACE editor.Example values: emacs, sublime, vim, vscode

Sync

NB_AUTO_SYNC

string

default:"1"

When set to 1, each git checkpoint call automatically runs nb sync. Set to 0 to disable automatic syncing.Supported values: 0, 1

NB_AUTO_SYNC_SECONDS

string

default:"60"

The minimum number of seconds between automatic Git sync operations when $NB_AUTO_SYNC is enabled.Supported values: 0 or any positive integer

Bookmarks

NB_BOOKMARK_CONTENT_CLEANUP_TOOL

string

default:"readability"

The tool used to clean up HTML content before converting it to Markdown when creating bookmarks.Supported tools: readability-cli, rdrviewSupported values: '' (none), rdrview, readability

NB_BOOKMARK_CONTENT_CONVERSION_TOOL

string

default:"pandoc"

The tool used to convert HTML content to Markdown when creating bookmarks.Supported tools: html-to-markdown, markitdown, pandocSupported values: '' (none), html-to-markdown, markitdown, pandoc

Browse / Server

NB_BROWSE_MARKDOWN_READER

string

default:"markdown+emoji+raw_html+east_asian_line_breaks"

The Pandoc reader — including any extensions — used for converting Markdown to HTML in nb browse. See the Pandoc extensions manual for details.

NB_BROWSE_SERVER_TOOL

string

default:"first available: ncat, socat, netcat, bash 5.2+"

The tool used to listen on the server host and port and respond to incoming HTTP requests.Supported values: accept, bash, nc, ncat, netcat, socat

NB_BROWSE_SUPPORT_LINKS

string

default:"1"

Set to 0 to hide the “Donate” and “Sponsor” links in nb browse.Supported values: 0, 1

NB_BROWSER

string

default:"value of $BROWSER"

The terminal browser command used by nb to open URLs.Example values: links, w3m

NB_GUI_BROWSER

string

default:""

The GUI browser command used to open URLs when a graphical browser is preferred.Example value: firefox

NB_SERVER_HOST

string

default:"localhost"

The host address for the nb browse server.

NB_SERVER_PORT

string

default:"6789"

The port number for the nb browse server.

Colors and Themes

NB_COLOR_PRIMARY

string

default:"depends on terminal capabilities"

The primary highlight color, specified as an xterm color number (typically 1–256). To view a table of available colors and their numbers, run nb settings colors.Supported values: 0–255+

NB_COLOR_SECONDARY

string

default:"8"

The color for lines and other accents, specified as an xterm color number. Run nb settings colors to view available options.Supported values: 0–255+

NB_COLOR_THEME

string

default:"nb"

The color theme for nb. Built-in and installed themes can be listed with nb settings colors.

NB_SYNTAX_THEME

string

default:"base16"

The syntax highlighting theme used when displaying code. Accepts any theme name listed by bat --list-themes.

Web / Custom

NB_CUSTOM_CSS

string

default:""

A CSS style sheet included inline within a <style> element on pages rendered by nb browse.

NB_CUSTOM_CSS_URL

string

default:""

A URL to an external CSS style sheet included via <link rel="stylesheet"> on pages rendered by nb browse.

NB_CUSTOM_JAVASCRIPT

string

default:""

A block of JavaScript code included inline within a <script> element on pages rendered by nb browse.

NB_CUSTOM_JAVASCRIPT_URL

string

default:""

A URL to an external JavaScript file included via <script src="//url"> on pages rendered by nb browse.

Data

NB_DATA_TOOL

string

default:"first available"

The tool used for viewing data files such as CSV and TSV.Example values: visidata, sc-im

NB_DEFAULT_EXTENSION

string

default:"md"

The default file extension for new notes created without an explicit extension.Example values: md, org

NB_DEFAULT_TEMPLATE

string

default:""

A string template or path to a template file used when creating new notes. Supports {{title}} and {{content}} placeholders.Example values: /path/to/template/file, # {{title}} {{content}}

NB_DIR

string

default:"$HOME/.nb"

The directory that contains all nb notebooks. Change this to keep notebooks in a non-default location such as a cloud-synced folder.

NB_DIRECTORY_TOOL

string

default:"'' (nb browse)"

The tool used for browsing and navigating notebook directories. When unset, nb browse is used.Example values: ranger, mc

Display

NB_FOLDERS_FIRST

string

default:"0"

When set to 1, folders are listed before other items in nb, nb ls, and nb browse.Supported values: 0, 1

NB_FOOTER

string

default:"1"

Controls display of the footer in nb and nb ls. Set to 0 to hide.Supported values: 0, 1

NB_HEADER

string

default:"2"

Controls display of the header in nb and nb ls.Supported values: 0, 1, 2, 3

NB_IMAGE_TOOL

string

default:"first available"

The tool used to render images in the terminal.Example values: imgcat, catimg

NB_LIMIT

string

default:"15"

The maximum number of items displayed by nb and nb ls. Set to auto to automatically limit output to the current terminal height.Supported values:

Format	Effect
`15`	Fixed maximum of 15 items
`auto`	Fit terminal height
`auto^15`	Auto with maximum of 15
`auto-2`	Auto minus 2 (for multiline prompts)
`auto+2`	Auto plus 2
`auto-2^15`	Auto minus 2, capped at 15
`auto+2^15`	Auto plus 2, capped at 15

NB_MARKDOWN_TOOL

string

default:"'' (default pager)"

The tool used to render Markdown content in the terminal. When unset, the default pager is used.Supported values: bat, glow, lowdown, mdcat, mdless, mdv

Encryption

NB_ENCRYPTION_TOOL

string

default:"openssl"

The encryption tool used when encrypting and decrypting items with nb add --encrypt and related commands.Supported values: gpg, openssl

Indicators

Indicators are the emoji characters shown next to items in listings. Each can be replaced with any character or string.

# example: use a custom pinned indicator
export NB_INDICATOR_PINNED="🔮"

NB_INDICATOR_AUDIO

string

default:"🔉"

Indicator shown next to audio files.

NB_INDICATOR_BOOKMARK

string

default:"🔖"

Indicator shown next to bookmark files (.bookmark.md).

NB_INDICATOR_DOCUMENT

string

default:"📄"

Indicator shown next to document files (PDF, DOCX, etc.).

NB_INDICATOR_EBOOK

string

default:"📖"

Indicator shown next to ebook files (EPUB, etc.).

NB_INDICATOR_ENCRYPTED

string

default:"🔒"

Indicator shown next to encrypted files.

NB_INDICATOR_FOLDER

string

default:"📂"

Indicator shown next to folders.

NB_INDICATOR_IMAGE

string

default:"🌄"

Indicator shown next to image files.

NB_INDICATOR_PINNED

string

default:"📌"

Indicator shown next to pinned items.

NB_INDICATOR_TODO

string

default:"✔️"

Indicator shown next to open (undone) todo items (.todo.md).

NB_INDICATOR_TODO_DONE

string

default:"✅"

Indicator shown next to completed (done) todo items.

NB_INDICATOR_VIDEO

string

default:"📹"

Indicator shown next to video files.

Other

NB_AUDIO_TOOL

string

default:"first available"

The tool used to play audio files.Example values: mplayer, afplay

NB_MATHJAX_ENABLED

string

default:"0"

Enable MathJax rendering in nb browse. Set to 1 to enable.Supported values: 0, 1

NB_PINNED_PATTERN

string

default:""

A pattern that, when matched in a filename or content, causes the item to be treated as pinned.Example value: #pinned

NB_USER_AGENT

string

default:""

The user agent string sent with HTTP requests made by nb (e.g., when fetching bookmark content). Defaults to the curl or wget default user agent.

NBRC_PATH

string

default:"$HOME/.nbrc"

The path to the nb configuration file. Change this to use a non-default location for your .nbrc.

Command Reference

Advanced

nb Environment Variables and Configuration Reference

Setting Variables

Editor

ACE Editor (Browse)

Sync

Bookmarks

Browse / Server

Colors and Themes

Web / Custom

Data

Display

Encryption

Indicators

Other

Build docs developers (and LLMs) love

Command Reference

Advanced

Documentation Index

​Setting Variables

​Editor

​ACE Editor (Browse)

​Sync

​Bookmarks

​Browse / Server

​Colors and Themes

​Web / Custom

​Data

​Display

​Encryption

​Indicators

​Other

Build docs developers (and LLMs) love

Setting Variables

Editor

ACE Editor (Browse)

Sync

Bookmarks

Browse / Server

Colors and Themes

Web / Custom

Data

Display

Encryption

Indicators

Other