nb - Notebook CLI

A fast, programmatic command-line interface for working with Jupyter notebooks. Designed for AI agents, automation scripts, and developers who need reliable notebook manipulation without opening a browser.

Installation

cargo build --release

The binary will be available at target/release/nb.

Quick Start

# Create and build a notebook
nb notebook create analysis.ipynb
nb cell add analysis.ipynb --source "import pandas as pd"
nb cell add analysis.ipynb --source "# Analysis" --type markdown
nb notebook read analysis.ipynb

# Execute and view results
nb notebook execute analysis.ipynb
nb notebook read analysis.ipynb --with-outputs

Local Mode

Default behavior. Operations directly modify .ipynb files.

Local mode lets you create, edit, execute, and query notebooks on disk without any server running. All changes are written directly to the .ipynb file.

# Create and edit
nb notebook create notebook.ipynb
nb cell add notebook.ipynb --source "x = 1 + 1"
nb cell update notebook.ipynb --cell 0 --source "x = 2 + 2"

# Read and search
nb notebook read notebook.ipynb              # View structure
nb notebook read notebook.ipynb --cell 0     # View specific cell
nb notebook search notebook.ipynb "import"   # Find patterns

# Execute locally (requires Python dependencies)
nb cell execute notebook.ipynb --cell 0
nb notebook execute notebook.ipynb           # Execute all cells

Python Dependencies for Local Execution

To execute notebooks in local mode, install:

pip install -r requirements.txt

Or manually:

pip install nbclient nbformat

Note: These dependencies are only required for local execution. Remote mode doesn't need them.

Remote Mode

Connect to a running JupyterLab server for real-time synchronization.

When you connect to a Jupyter server, the CLI uses Y.js for conflict-free real-time updates. Changes appear instantly in your open JupyterLab tabs, and you can execute code using the server's kernel.

Connect to a Server

Auto-detection (recommended):

nb connect

Automatically finds running Jupyter servers using jupyter server list, validates them, and connects. If multiple servers are found, you'll get an interactive prompt to choose one.

Manual connection:

nb connect --server http://localhost:8888 --token your-jupyter-token

Connection options:

• --server: Server URL (e.g., http://localhost:8888)
• --token: Authentication token from Jupyter

Connection Persistence

Connection info is saved in .jupyter/cli.json in the current directory. All subsequent commands automatically use this connection until you disconnect or change directories.

# Connect once (auto-detect)
nb connect

# Future commands use saved connection
nb cell add notebook.ipynb --source "df.head()"
nb cell execute notebook.ipynb --cell 0

# Check current connection
nb status

# Disconnect when done
nb disconnect

How it works: When connected, the CLI detects if a notebook is open in JupyterLab and uses Y.js for instant sync. If the notebook isn't open on the server, operations fall back to file-based mode.

Remote Mode Examples

# Connect automatically
nb connect

# Add cell - appears instantly in JupyterLab
nb cell add experiment.ipynb --source "df.describe()"

# Update cell in real-time
nb cell update experiment.ipynb --cell 0 --append "\nprint('done')"

# Execute via remote kernel
nb cell execute experiment.ipynb --cell 0

# Disconnect when switching projects
nb disconnect

Commands

Use --help with any command for full details and options.

Key Features

Cell Referencing

Two ways to reference cells:

• Index: --cell 0 (position-based, supports negative indexing: -1 = last cell)
• ID: --cell-id "my-cell" (stable, doesn't change when cells move)

Output Format

Control output format for better integration with your workflow:

• JSON (default): Structured, nbformat-compliant for programmatic use
• Text (-f text): Human-readable for terminal viewing

nb notebook read notebook.ipynb -f text

Multi-line Code

Escape sequences are automatically interpreted:

# Add cell with proper formatting
nb cell add notebook.ipynb \
  --source 'def hello():\n    print("world")\n\nhello()'

# Append to existing cell
nb cell update notebook.ipynb --cell 0 \
  --append '\n# Added comment\nprint("more")'

Common Workflows

Build notebook programmatically:

nb notebook create analysis.ipynb --template basic
nb cell add analysis.ipynb --source "import pandas as pd"
nb cell add analysis.ipynb --source "# Analysis" --type markdown
nb notebook execute analysis.ipynb

Debug and fix cells:

# Find problematic cells
nb notebook search notebook.ipynb --with-errors

# Inspect specific cell with outputs
nb notebook read notebook.ipynb --cell 5 --with-outputs

# Fix the cell
nb cell update notebook.ipynb --cell 5 --source "fixed code"

# Re-execute
nb cell execute notebook.ipynb --cell 5

Extract specific content:

nb notebook read notebook.ipynb --only-code      # All code cells
nb notebook read notebook.ipynb --only-markdown  # All markdown
nb notebook read notebook.ipynb --cell -1        # Last cell

For AI agents:

# Analyze all code in a notebook
nb notebook read notebook.ipynb --only-code

# Find cells with errors
nb notebook search notebook.ipynb --with-errors

# Add analysis cell and execute
nb cell add experiment.ipynb --source "df.describe()"
nb cell execute experiment.ipynb --cell -1

Examples

See examples/ directory for sample notebooks demonstrating various cell types and outputs.

License

BSD-3-Clause