nb-api
Typed Rust interface to the nb note-taking CLI.
Purpose
nb-api provides a programmatic Rust client for nb, the command-line
note-taking tool. It wraps nb as a subprocess, handling argument escaping,
notebook qualification, output parsing, and error recovery.
This crate is designed for use by:
nb-mcp-server— the MCP server that exposesnbto LLM assistantsnbspec— notebook-first OpenSpec orchestration- Any Rust application that needs to drive
nbprogrammatically
nb-api is intentionally free of MCP-specific dependencies (rmcp,
schemars). The schemars feature is available as an optional add-on for
consumers that need JSON Schema generation (e.g., MCP tool parameters).
Quick Start
Prerequisites
Install nb by following the official instructions:
nb installation guide.
Usage
Add to your Cargo.toml:
[]
= "0.1"
With optional JSON Schema support:
[]
= { = "0.1", = ["schemars"] }
Example
use ;
async
API Surface
All operations return Result<String, NbError> with raw ANSI-stripped CLI
output. Typed accessor methods may be added in future versions.
Notes
| Method | Description |
|---|---|
add_note |
Create a note (title, content, tags, folder) |
show_note |
Read a note's content |
edit_note |
Update a note (mode selects Overwrite (destructive: replaces every byte), Append, or Prepend) |
delete_note |
Delete a note |
move_note |
Move or rename a note |
list_notes |
List notes with optional filtering |
search_notes |
Full-text search with OR/AND semantics |
Todos
| Method | Description |
|---|---|
add_todo |
Create a todo item with optional checklist |
mark_task_done |
Mark a todo (or specific task) as complete |
unmark_task_done |
Reopen a completed todo (or specific task) |
list_tasks |
List checklist items within todos, with optional status filter |
Organization
| Method | Description |
|---|---|
add_bookmark |
Save a URL as a bookmark |
import_note |
Import a file or URL |
list_folders |
List folders in a notebook |
add_folder |
Create a folder |
list_notebooks |
List available notebooks |
show_notebook_status |
Show notebook status |
show_notebook_path |
Get the filesystem path for a notebook |
Types
| Type | Description |
|---|---|
NbClient |
Async client for invoking nb commands |
NbError |
Error type for all operations |
Config |
Configuration for constructing NbClient |
EditMode |
Content update mode for edit_note (Overwrite is destructive: replaces every byte of the note body). Canonical serialization is overwrite; the legacy string replace is accepted as a serde alias for backward compatibility but is not advertised in the derived JSON Schema. |
SearchMode |
Query matching mode (any, all) |
TaskStatus |
Todo status filter (open, closed) |
Configuration
Config contains only nb-relevant fields:
| Field | Type | Default | Description |
|---|---|---|---|
notebook |
Option<String> |
None |
Default notebook name (overrides Git-derived fallback) |
create_notebook |
bool |
true |
Automatically create missing notebooks |
allow_top_level_notes |
bool |
false |
Allow notes at notebook root without a folder |
disable_git_signing |
bool |
false |
Disable Git commit/tag signing for nb subprocesses |
Notebook Resolution
Priority order:
- Per-command
notebookargument (highest) Config.notebookfield- Git-derived default from the master worktree path
The NB_MCP_NOTEBOOK environment variable is not read by nb-api.
That is an MCP-server-specific convention resolved by nb-mcp-server before
constructing Config.
Features
| Feature | Default | Description |
|---|---|---|
schemars |
disabled | Adds JsonSchema derive to EditMode, SearchMode, TaskStatus |
testing |
disabled | Exposes the nb_api::testing module with NbTestEnv and friends; pulls in tempfile as a dependency. Use for integration tests of consumers. |
testing-tokio |
disabled | Within nb_api::testing, reveals the async helpers NbTestEnv::configure_tokio and NbTestEnv::nb_command_async. The crate's own tokio usage (in NbClient) is unconditional and does not depend on this flag. Pair with testing to reach the async helpers. |
License
Repository History
This crate was extracted from
emcd/nb-mcp-server, where it lived
as a workspace member at nb-api/. The nb-api 0.1.0 release was published
from that repository.
Starting with 0.1.1, nb-api is developed and published from this
repository (emcd/nb-api). The split is governed by the
split-nb-api-repository
OpenSpec proposal.
Git history begins fresh in this repository. Pre-split history (the work
extracted from nb-mcp-server/nb-api/) is preserved at
emcd/nb-mcp-server on the
master branch. Archaeologists tracing the lineage of a particular change
should look there first.