bunbook-cli

CLI for BunBook — run, export, and convert TypeScript notebooks from the terminal or CI pipelines.

Requirements

Bun installed and available in your PATH.

Usage

No install needed — use bunx:

bunx bunbook-cli --help

USAGE bunbook run|export-ts|import-ts|export-html|export-md|remove-outputs

COMMANDS

        run    Execute all cells and save outputs to .ipynb
  export-ts    Convert notebook to a runnable .ts file
  import-ts    Convert a .ts file (with // %% separators) to a notebook
export-html    Export notebook to self-contained .html with interactive charts
  export-md    Export notebook to .md
remove-outputs Strip all outputs and execution counts from a notebook

Use bunbook <command> --help for more information about a command.

Commands

run

Execute all cells and save outputs back to the notebook file.

bunx bunbook-cli run notebook.ipynb
bunx bunbook-cli run notebook.ipynb -o result.ipynb

export-html

Export to a self-contained HTML file with interactive Plotly charts.

bunx bunbook-cli export-html notebook.ipynb
bunx bunbook-cli export-html notebook.ipynb -o report.html
bunx bunbook-cli export-html notebook.ipynb --run          # execute first, then export
bunx bunbook-cli export-html notebook.ipynb --hide-output    # code only, no outputs
bunx bunbook-cli export-html notebook.ipynb --hide-code      # outputs only, no code

export-md

Export to a Markdown file with fenced code blocks.

bunx bunbook-cli export-md notebook.ipynb
bunx bunbook-cli export-md notebook.ipynb -o README.md
bunx bunbook-cli export-md notebook.ipynb --run
bunx bunbook-cli export-md notebook.ipynb --hide-output      # code only, no outputs
bunx bunbook-cli export-md notebook.ipynb --hide-code        # outputs only, no code

export-ts

Convert a notebook to a runnable .ts file with // %% cell separators.

bunx bunbook-cli export-ts notebook.ipynb
bunx bunbook-cli export-ts notebook.ipynb -o script.ts
bunx bunbook-cli export-ts notebook.ipynb --run

import-ts

Convert a .ts file (with // %% cell separators) back to a notebook.

bunx bunbook-cli import-ts script.ts
bunx bunbook-cli import-ts script.ts -o notebook.no-output.ipynb

remove-outputs

Strip all outputs and execution counts from a notebook. Useful before committing.

bunx bunbook-cli remove-outputs notebook.ipynb           # in-place
bunx bunbook-cli remove-outputs notebook.ipynb -o clean.ipynb

Options

All commands accept:

| Flag | Short | Description | |---|---|---| | --output <path> | -o | Output file path (defaults vary by command) | | --help | -h | Show help for the command |

Export commands (export-html, export-md, export-ts) additionally accept:

| Flag | Short | Description | |---|---|---| | --run | -r | Execute the notebook before exporting |

export-html and export-md additionally accept:

| Flag | Short | Description | |---|---|---| | --hide-code | -C | Exclude code (show only outputs and markdown) | | --hide-output | -O | Exclude outputs (show only code and markdown) |

CI Example

Run a notebook and publish the HTML output as a build artifact:

- run: bunx bunbook-cli export-html report.ipynb --run -o report.html