nbsee
=====

Simple CLI viewer for Jupyter notebooks focused on fast reading and easy copying of code and text outputs from the terminal.

Status: planning/design. See docs/TODO.md for the working task list.

Goals (MVP)
- Interactive terminal viewer for `.ipynb`.
- Navigate cells with keys; focus input vs output.
- Code cells: show source and text/plain outputs only.
- Easy copying from the viewer using the keyboard (xclip).
- Ignore images/HTML-rich outputs for now.

Quick Concept (not implemented yet)
- `nbsee notebook.ipynb` — open an interactive viewer.

Key bindings (proposed)
- `j`/`k`: move to next/previous cell
- Arrow Up/Down: scroll the view line-by-line
- PageUp/PageDown: page scroll
- Ctrl+u / Ctrl+d: half-page scroll up/down
- `Tab`: toggle focus between input (code/markdown) and output (text/plain)
- If a cell has no text output, `Tab` does nothing and shows a brief message.
- `y`: copy the currently focused region to clipboard using `xclip -selection clipboard`
- `z`: hide/show all outputs (fold outputs)
- `Shift+V`: start/stop visual selection for inputs; use `j`/`k` to expand/shrink; `y` copies all selected code cells
- `/`: search (inputs+outputs). Enter to submit, `Esc` cancels
- `n` / `N`: next/prev match
- `gg` / `G`: jump to first / last cell
- `G`/`gg`: jump to last/first cell (optional)
- `q`: quit

Notes
- Copying uses Linux X11 clipboard via `xclip`. Wayland/macOS not targeted in MVP.
- When an output is not available (e.g., no text/plain), copy will show an inline message.
- Python syntax highlighting is built-in via Rich.

Install (PyPI)
- `python -m pip install nbsee`
- Run: `nbsee path/to/notebook.ipynb`

Development (uv)
- Quick run without installing: `uv run -m nbsee path/to/notebook.ipynb`
- Run tests: `uv run pytest`
- Lint/format check: `uv run ruff check .` and `uv run ruff format --check .`
- Build distributions: `uv build`
- Release: push a tag like `v0.1.0` to trigger `.github/workflows/publish.yml` (requires PyPI trusted publishing setup).
- Install editable and use `nbsee` command:
  - Create venv: `uv venv`
  - Activate: `source .venv/bin/activate`
  - Install: `uv pip install -e .`
  - Run: `nbsee path/to/notebook.ipynb`
- Clipboard requirement: `xclip` on Linux/X11 must be installed and available in `PATH`.


Docs
- Design: `docs/DESIGN.md`
- TODOs & roadmap: `docs/TODO.md`
