Notebook CLI

Notebook CLI

Use nb for every .ipynb operation. Do not read, write, patch, or edit notebook JSON directly when nb can perform the task.

Core Rules

• Inspect before editing: run nb read <notebook> --no-output unless outputs are relevant.
• Prefer the default AI-Optimized Markdown output from nb read; use --json only when nbformat JSON is specifically needed.
• Prefer cell IDs (--cell / -c) for durable edits after inspecting a notebook. Use indexes (--cell-index / -i) for quick positional work; negative indexes are supported.
• Use --no-output when summarizing structure or source. Include outputs only when diagnosing results, failures, plots, or displayed values.
• Use stdin (--source -) for multi-line or quoted content to avoid shell escaping mistakes.
• If the user specifies uv or the workspace is clearly a uv project, treat uv as the notebook execution environment for the whole task. Use --uv on nb commands that support it, such as nb create and nb execute.
• When creating a notebook with several sections, add cells in batches of roughly 3–5 cells grouped by logical section using multi-cell sentinels (@@markdown, @@code). Execute and verify each batch before adding the next. Do not add the entire notebook in one call — it increases latency and makes errors harder to catch.
• Every markdown cell must contain a heading and at least one sentence of prose explaining what the following code does or why it matters. A bare heading is not sufficient — see best-practices.md.
• When notebook code depends on third-party packages, add a dependency-install cell at the top of the notebook before imports if package availability is uncertain.
• If a uv environment is present, the dependency cell should use !uv pip install ....
• If a uv environment is not present, the dependency cell should use %pip install ....
• Run nb <command> --help or nb cell <subcommand> --help when command syntax is uncertain.
• In connected mode, let nb use the saved connection from nb connect. Do not write secret tokens into commands, prompts, logs, or examples; if auto-detection is unavailable, ask the user to establish the connection manually.
• Before running non-notebook Python commands that should match the active notebook environment, use nb status --python and run commands through the returned prefix.

Trust Boundary

nb is an external executable that can read notebook content and, in connected mode, use saved Jupyter connection state. Before first use in a workspace, verify the command you will run:

command -v nb
nb --version

Use the repository-built or documented nb-cli binary. If nb is missing, resolves to an unexpected path, or reports an unexpected version/name, stop and ask the user to install or select the trusted nb-cli binary. Do not pass notebook contents, outputs, server URLs, or connection state to an unverified executable.

Common Workflows

Create a Notebook

nb create analysis.ipynb
nb create analysis.ipynb --kernel python3
nb create notes.ipynb --markdown

Read references/create.md when creating new notebooks, choosing kernels, or overwriting an existing notebook.

Inspect a Notebook

nb read analysis.ipynb --no-output
nb read analysis.ipynb --cell-index 3
nb search analysis.ipynb "fit_model"

Read references/read.md for filters, output handling, and parsing the AI markdown format.

Edit Cells

nb cell update analysis.ipynb --cell "cell-id" --source -
nb cell add analysis.ipynb --type markdown --source "# Results"
nb cell delete analysis.ipynb --cell-index -1

Read references/edit-cells.md before making multi-cell edits, preserving metadata, inserting around cell IDs, or deleting ranges.

Execute and Debug

nb execute analysis.ipynb --cell-index 4
nb execute analysis.ipynb --start 0 --end 5 --allow-errors
nb read analysis.ipynb --cell-index 4

Read references/execute.md for kernel selection, timeouts, environment flags, and failure-oriented workflows.

Work with JupyterLab

nb connect
nb status
nb cell update analysis.ipynb --cell "cell-id" --source -
nb disconnect

Read references/connect-mode.md when a notebook is open in JupyterLab or changes must sync through a running server.

Manage Outputs

nb read analysis.ipynb --limit 8000 --output-dir ./notebook-outputs
nb output clear analysis.ipynb
nb output clean

Read references/output-format.md for sentinel parsing, externalized output files, clearing outputs, and commit hygiene.

Author Quality Notebooks

Read references/best-practices.md for research-based guidelines on narrative structure, code organization, reproducibility, and naming conventions when creating or reviewing notebooks.

Permission Note

If the agent cannot run nb or connected-mode commands because of sandbox policy, ask the user to allow the needed command. For recurring use, the project or user rules should allow the nb command prefix.

Validation Prompts

Use references/validation-prompts.md when checking whether this skill still guides agents toward the intended nb workflows.