alt="nb"
width="200">

alt="Build Status"
style="max-width:100%;">

nb is a command line and local web
note‑taking, bookmarking, archiving,
and knowledge base application
with:

- plain text data storage,
- encryption,
- filtering, pinning, #tagging, and search,
- Git-backed versioning and syncing,
- Pandoc-backed conversion,
- [[wiki-style linking]],
- terminal and GUI web browsing,
- inline images,
- todos with tasks,
- global and local notebooks,
- organization with folders,
- customizable color themes,
- extensibility through plugins,

and more, in a single portable script.

nb creates notes in text-based formats like
Markdown,
Org,
LaTeX,
and AsciiDoc,
can work with files in any format,
can import and export notes to many document formats,
and can create private, password-protected encrypted notes and bookmarks.
With nb, you can write notes using
Vim,
Emacs,
VS Code,
Sublime Text,
and any other text editor you like,
as well as terminal and GUI web browsers.
nb works in any standard Linux / Unix environment,
including macOS and Windows via WSL, MSYS, and Cygwin.
Optional dependencies can be installed to enhance functionality,
but nb works great without them.

alt="home"
width="450">

nb is also a powerful bookmarking system featuring:

- locally-served, text-centric, distraction-free bookmark browsing
in terminal and GUI web browsers,
- local full-text search of cached page content with regular expression support,
- convenient filtering and listing,
- Internet Archive Wayback Machine snapshot lookup
for broken links,
- tagging, pinning, linking, and full integration with other nb features.

Page information is
downloaded,
cleaned up,
structured,
and saved
into normal Markdown documents made for humans,
so bookmarks are easy to view and edit just like any other note.

alt="nb browse"
width="500">

nb uses Git in the background to
automatically record changes and sync notebooks with remote repositories.
nb can also be configured to
sync notebooks using a general purpose syncing utility like Dropbox
so notes can be edited in other apps on any device.

alt="nb list empty"
width="450">

nb is designed to be portable, future-focused, and vendor independent,
providing a full-featured and intuitive experience within
a highly composable multimodal user-centric text interface.
The entire program is contained within
a single well-tested shell script
that can be
installed, copied, or curled almost anywhere and just work,
using a strategy inspired by
progressive enhancement
for various experience improvements in more capable environments.
nb works great whether you have one notebook with just a few notes
or dozens of notebooks containing thousands of notes, bookmarks, and other items.
nb makes it easy to incorporate other tools, writing apps, and workflows.
nb can be used a little, a lot, once in a while, or for just a subset of features.
nb is flexible.

$3

#### Dependencies

##### Required

- Bash)
- nb works perfectly with Zsh, fish, and any other shell
set as your primary login shell,
the system just needs to have Bash available on it.
- Git
- A text editor with command line support, such as:
- Vim),
- Emacs,
- Visual Studio Code,
- Sublime Text,
- Helix,
- micro,
- nano,
- Atom,
- TextMate,
- MacDown,
- some of these,
- and many of these.

##### Optional

nb leverages standard command line tools
and works in standard Linux / Unix environments.
nb also checks the environment for some additional optional tools and
uses them to enhance the experience whenever they are available.

Recommended:

- bat
- ncat or socat
- pandoc
- rg
- tig
- w3m

Also supported for various enhancements:

Ack,
afplay,
asciidoctor,
The Silver Searcher (ag),
catimg,
Chafa,
Chromium / Chrome,
eza,
ffplay,
ImageMagick,
glow,
GnuPG,
highlight,
imgcat,
joshuto,
kitty's icat kitten,
lowdown,
lsd,
Links),
Lynx),
mdcat,
mdless,
mdv,
Midnight Commander (mc),
mpg123,
MPlayer,
ncat,
netcat,
note-link-janitor
(via plugin),
pdftotext,
Pygments,
Ranger,
readability-cli,
rga / ripgrep-all,
sc-im,
socat,
termvisage,
termpdf.py,
Tidy-Viewer (tv),
timg,
vifm,
viu,
VisiData

#### macOS / Homebrew

``bash
brew install xwmx/taps/nb
`

Installing nb with Homebrew also installs
the recommended dependencies above
and completion scripts for Bash, Zsh, and Fish.

Install the latest development version from the repository with:

`bash
brew install xwmx/taps/nb --head
`

nb is also available in
homebrew-core.
Installing it together with the bash formula is recommended:

`bash
brew install nb bash
`

#### Ubuntu, Windows, and others

##### npm

`bash
npm install -g nb.sh
`

After npm installation completes, run
sudo "$(which nb)" completions install
to install Bash and Zsh completion scripts (recommended).

On Ubuntu and WSL, you can
run sudo "$(which nb)" env install
to install the optional dependencies.

When nb is installed on Windows,
socat (MSYS,
Cygwin) is recommended.

*nb is also available under its original package name,
notes.sh,
which comes with an extra notes executable wrapping nb.*

##### Download and Install

To install as an administrator,
copy and paste one of the following multi-line commands:

`bash


install using wget

On Ubuntu and WSL, you can
run sudo nb env install to install the optional dependencies.

###### User-only Installation

To install with just user permissions, simply
add the nb script to your $PATH.
If you already have a ~/bin directory, for example, you can
use one of the following commands:

`bash


download with wget

Installing with just user permissions doesn't include
the optional dependencies or completions,
but nb core functionality works without them.
If you have sudo access and want
to install the completion scripts and dependencies, run the following command:

`bash
sudo nb env install
`

##### Make

To install with Make),
clone this repository, navigate to the clone's root directory, and run:

`bash
sudo make install
`

This will also install the completion scripts on all systems and
the recommended dependencies on Ubuntu and WSL.

##### bpkg

To install with bpkg:

`bash
bpkg install xwmx/nb
`

##### basher

To install with basher:

`bash
basher install xwmx/nb
`

#### Tab Completion

Bash, Fish, and Zsh tab completion should be enabled
when nb is installed using the methods above,
assuming you have the appropriate system permissions or installed with sudo.
If completion isn't working after installing nb, see the
completion installation instructions.

#### Updating

When nb is installed using a package manager like npm or Homebrew,
use the package manager's upgrade functionality to update nb to
the latest version.
When installed via other methods,
nb can be updated to the latest version using
the nb update subcommand.

Overview

To get started, simply run:

`bash
nb
`

nb sets up your initial home notebook the first time it runs.

By default, notebooks and notes are global (at ~/.nb),
so they are always available to nb
regardless of the current working directory.
nb also supports local notebooks.

$3

#### Adding



↑ ·
nb add,
nb browse add



Use nb add (shortcuts: nb a, nb +)
to create new notes:

`bash


create a new note in your text editor

nb add with no arguments or input will open the new, blank note
in your environment's preferred text editor.
You can change your editor using
the $EDITOR environment variable
or nb set editor.

nb files are Markdown
files by default. The default file type can be changed to
whatever you like
using nb set default_extension.

nb add has intelligent argument parsing
and behaves differently depending on the types of arguments it receives.
When a filename with extension is specified,
a new note with that filename is opened in the editor:

`bash
nb add example.md
`

When a string is specified, a new note is immediately created
with that string as the content and without opening the editor:

`bash
❯ nb add "This is a note."
Added: [1] 20200101000000.md
`

nb add is useful for quickly jotting down notes directly
via the command line. Quoting content is optional, but recommended.

When no filename is specified, nb add uses the current datetime as
the filename.

nb add can also receive piped content, which behaves the same as
nb add :

`bash


create a new note containing "Note content."

Content can be passed with the --content option,
which also creates a new note without opening the editor:

`bash
nb add --content "Note content."
`

When content is piped,
specified with --content ,
or passed as a string argument,
use the --edit flag to open the file in the editor
before the change is committed.

The title, filename, and content can also be specified with long and
short options:

`bash
❯ nb add --filename "example.md" -t "Example Title" -c "Example content."
Added: [9] example.md "Example Title"
`

The -t