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.