# nb-cli - AI 에이전트와 노트북 자동화를 위한 CLI

> Clean Markdown view of GeekNews topic #29871. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=29871](https://news.hada.io/topic?id=29871)
- GeekNews Markdown: [https://news.hada.io/topic/29871.md](https://news.hada.io/topic/29871.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-05-26T09:20:01+09:00
- Updated: 2026-05-26T09:20:01+09:00
- Original source: [blog.jupyter.org](https://blog.jupyter.org/nb-cli-a-command-line-interface-for-ai-agents-and-notebook-automation-996ad7edacd9)
- Points: 1
- Comments: 1

## Topic Body

- AI 코딩 에이전트가 Jupyter 노트북을 **아티팩트로 다룰 수 있도록** 설계된 실험적 오픈소스 CLI 도구로, Rust 기반으로 구현되어 빠르고 안정적인 노트북 조작을 지원  
- `.ipynb` JSON 구조가 자동화·LLM 처리에 적합하지 않다는 문제를 해결하기 위해, **nbformat 사양**을 따르면서 읽기·쓰기·실행·검색 기능을 명령줄로 제공  
- **Jupyter 서버 없이도 동작**하며, 서버에 연결할 경우 JupyterLab과 동일한 **Y.js CRDT 프로토콜**로 실시간 협업 편집 지원  
- LLM 컨텍스트 효율을 위해 `@@cell`, `@@output` 같은 **센티넬 기반 AI 최적화 마크다운 포맷**을 새롭게 설계  
- Unix 조합성, 안정적 셀 참조, 강력한 검색, 다중 셀 일괄 조작, 환경 인식 실행 등 **에이전트 워크플로우에 맞춘 기능**을 통합 제공  
  
---  
  
### 배경: 노트북이 가진 “블랙박스” 문제  
  
- AI 코딩 에이전트가 부상하면서 개발자 도구의 정의가 바뀌고 있으며, Claude·GPT 같은 LLM은 문서·Stack Overflow·GitHub의 방대한 CLI 사용 사례로 학습되어 **커맨드라인 인터페이스 활용에 매우 능숙함**  
- 기존 도구들은 노트북 안에서 에이전트를 실행하는 데 초점을 맞춰왔지만, **노트북 자체를 아티팩트로 다루는 에이전트**를 위한 도구는 비어 있었음  
- Jupyter 노트북의 `.ipynb` JSON 구조는 셸 스크립트·LLM에서 **프로그래밍적 처리가 어려운 마찰점**으로 작용  
- 자동화·AI 분석이 필요한 다음 시나리오에서 기존 인터페이스가 부족함  
  - **자율 분석**: 데이터 과학 워크플로우를 감사하는 AI 에이전트가 셀 단위로 파이프라인을 파악해야 함  
  - **자동 검증**: CI/CD 시스템이 노트북을 실행하고 출력을 검증하며 오류를 사전에 잡아야 함  
  - **대규모 문서화**: 노트북 내용을 깔끔한 문서로 자동 변환해야 함  
  - **운영 환경 디버깅**: 헤드리스 환경에서 노트북 실행 실패를 수동 개입 없이 진단해야 함  
  - **데이터로서의 노트북**: 노트북을 구조화된 데이터베이스처럼 다루어 보고서·요약·시각화를 생성  
- 기존에는 JupyterLab UI를 수동으로 다루거나, 복잡한 JSON을 파싱하는 **취약한 Python 스크립트**를 작성하거나, 실시간 통합이 없는 실행 도구를 쓰는 방식이 일반적이었음  
- nb-cli는 **CLI 우선 인터페이스**와 Unix 조합성을 활용해, 노트북을 소프트웨어 스택의 1급 시민으로 다룰 수 있게 함  
  
### 핵심 기능  
  
- ## Jupyter 서버 유무에 관계없이 동작  
  - 기본적으로 `.ipynb` 파일을 직접 읽고 쓰며, **ZeroMQ를 통해 커널과 직접 통신**해 실행  
  - 서버 실행이 불필요한 스크립트·CI 파이프라인에 적합  
    - `nb create analysis.ipynb` 로 서버 없이 노트북 생성  
    - `nb cell add`, `nb execute`, `nb read` 명령으로 셀 추가·실행·결과 조회 가능  
  - 여러 사용자·에이전트가 동시에 같은 노트북을 편집할 때는 서버 연결이 유용하며, JupyterLab이 내부적으로 쓰는 것과 같은 **Y.js CRDT 프로토콜**로 충돌 없는 실시간 동기화 제공  
    - `nb connect`로 로컬 서버 자동 감지, `--server` 옵션으로 특정 서버·토큰 지정 가능  
    - `--restart-kernel` 옵션으로 재현성 점검을 위한 커널 재시작 실행 지원  
  - 서버 연결 시 JupyterLab에서 노트북이 열려 있는지 감지하고, 열려 있지 않으면 파일 기반 동작으로 자연스럽게 폴백  
  
- ## AI 최적화 마크다운 포맷  
  - 언어 모델은 JSON을 파싱하지 않고 **토큰을 예측**하므로, 깊게 중첩된 Jupyter JSON은 컨텍스트 윈도우에서 비효율적  
  - Jupyter 기본 포맷은 소스가 문자열 배열, 출력이 base64 블롭, 메타데이터가 다층 중첩으로 구성되어 있어, LLM 입장에서 **토큰의 30~40%가 중괄호·대괄호·이스케이프 같은 구조 문자**로 의미 없이 소모됨  
  - 일반 Markdown은 토큰 효율은 좋지만 모호함이 큼  
    - `#`이 마크다운 헤딩인지 Python 주석인지 구분 불가  
    - 코드 펜스가 노트북 셀인지 문서 내 예시인지 구분 불가  
    - "7번 셀의 오류를 고쳐줘"라고 했을 때 셀 위치를 안정적으로 식별할 구조적 마커 부재  
  - 이를 해결하기 위해 **라인 단위 센티넬 포맷**을 설계  
    - `@@notebook`, `@@cell`, `@@output` 같은 센티넬로 명확한 구조 경계 제공  
    - 센티넬 라인에 셀 타입·인덱스·실행 횟수를 **인라인 JSON 메타데이터**로 표기해, 어텐션 메커니즘이 정보를 찾는 방식과 정렬  
    - 언어 힌트가 붙은 코드 펜스로 모델의 구문 학습 활성화  
    - 각 셀 블록이 자기완결적이라 **잘려도 점진적으로 손상**되며, JSON처럼 한 군데 잘리면 전체 구조가 깨지는 문제가 없음  
  
- ## 조합 가능한 설계  
  - Unix 관례를 따라 **plain text 출력, stdin 지원, 예측 가능한 종료 코드** 제공  
  - 에이전트 입장에서 단일 셸 명령이 여러 번의 도구 호출·중간 파싱을 대체 가능  
  - "노트북에 요약 섹션을 추가하고 실행" 같은 작업을, 셀 추가·실행·결과 읽기를 **하나의 셸 호출로 처리** 가능  
    - `nb cell add ... && nb execute ... && nb read ...` 형태로 체이닝  
    - 에이전트는 노트북 전체를 다시 읽지 않고 필요한 출력만 받음  
  - 디버깅에도 동일 원칙 적용  
    - `nb search analysis.ipynb --with-errors` 한 번으로 오류가 난 셀만 반환, 성공한 셀에 토큰을 낭비하지 않음  
  
- ## 안정적 셀 참조  
  - 두 가지 셀 참조 방식 지원  
    - **인덱스 기반** `--cell-index 0` (음수 인덱싱 지원, `-1`은 마지막 셀)  
    - **ID 기반** `--cell f68t57` (셀이 이동해도 변하지 않음)  
  - `nb cell update ... --cell-index 0 --source "x = 42"` 처럼 위치로 참조하거나  
  - `nb cell update ... --cell ce456 --source "print('Done')"` 처럼 **안정 ID로 참조**해 셀 재정렬에도 안전  
  
- ## 강력한 검색 기능  
  - 셀 내용·타입·실행 오류로 빠르게 위치 탐색 가능  
  - 기본은 셀 소스 코드 매칭, **scope 필터로 실행 출력까지 확장**  
    - `nb search analysis.ipynb "import pandas"` 패턴 검색  
    - `nb search analysis.ipynb --with-errors` 오류 셀만 추출  
    - `nb search analysis.ipynb "KeyError" --scope output` 출력에서 검색  
    - `nb search analysis.ipynb "TODO" --cell-type markdown` 셀 타입으로 필터  
  - 에이전트는 `--with-errors`로 **실패 셀만 받아 처리**하고, `--scope output`과 결합해 에러 트레이스백을 직접 검색 가능  
  - 사람도 deprecated API 감사, 대형 노트북에서의 함수 위치 파악, 리팩터 전 패턴 추출에 활용 가능  
  
- ## 다중 셀 일괄 조작  
  - 마크다운 헤더 → 설정 코드 → 분석 같은 셀 시퀀스 추가가 흔한 패턴이며, 셀 하나씩 추가하면 왕복 횟수와 인덱스 관리 부담 증가  
  - **센티넬 포맷으로 한 호출에 여러 셀 추가** 지원  
    - `@@markdown`, `@@code` 블록을 heredoc으로 묶어 한 번에 전달  
    - `@@cell {"cell_type": "..."}` 형태의 전체 JSON 포맷도 지원  
  - stdin과도 호환되어 스크립트·파이프라인에서 셀 구성 용이  
    - `printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -`  
  - 동일한 일괄 처리 철학이 실행·삭제에도 적용  
    - `nb execute analysis.ipynb --start 2 --end 5` 범위 실행  
    - `nb cell delete analysis.ipynb -i 0 -i 2` 특정 셀 삭제  
    - `nb cell delete analysis.ipynb --range 0:3` 범위 삭제  
  
- ## 환경 인식 실행  
  - `nb connect`, `nb execute`, `nb create`에서 **`--uv`, `--pixi` 플래그** 지원, 해당 환경 매니저로 Jupyter 서버·커널 탐색  
  - `nb status --python`은 연결된 커널과 동일 환경에서 Python을 실행할 명령 프리픽스 반환  
    - 반환값 예: `"uv run"`, `"pixi run"`, 시스템 Python의 경우 빈 값  
    - `$(nb status --python) python -c "..."` 형태로 파이프라인에 활용  
  
### 실제 사용 사례  
  
- ## AI 에이전트 워크플로우  
  - 실패 셀 탐색 → 코드 수정 → 재실행을 명령으로 연결해 **분석 워크플로우의 일부로 노트북 조작** 가능  
    - `nb search data_analysis.ipynb --with-errors`  
    - `nb cell update data_analysis.ipynb --cell-index 3 --source "df = pd.read_csv('data.csv', encoding='utf-8')"`  
    - `nb execute data_analysis.ipynb --cell-index 3`  
  
- ## CI/CD 통합  
  - 지속적 통합 파이프라인에서 노트북의 **자동 테스트와 검증** 수행  
    - `nb execute pipeline.ipynb --allow-errors`로 실행 후, `nb search ... --with-errors`로 오류 확인 시 종료 코드 1 반환  
    - 커밋 전 `nb output clear`로 출력 정리  
  
- ## 프로그래밍 방식 노트북 생성  
  - 문서·보고서·분석을 자동 생성  
    - `nb create report.ipynb`로 보고서 노트북 생성  
    - 멀티셀 명령으로 제목·소개·분석 코드를 한 번에 추가하고 `nb execute`로 출력 채움  
  
- ## 운영 환경 노트북 디버깅  
  - 배포된 노트북의 문제를 신속히 진단  
    - `nb search failing_notebook.ipynb --with-errors` 오류 셀 추출  
    - `nb search analysis.ipynb "pandas.np"` deprecated API 사용 탐색  
    - `nb search notebook.ipynb "eval("` 보안 우려 패턴 탐색  
    - `nb read failing_notebook.ipynb --cell-index 5` 특정 셀의 전체 출력 확인  
    - `nb execute failing_notebook.ipynb --restart-kernel` 깨끗한 재현성 점검  
  
### 실제 동작 예시  
  
- ## Example 1: Claude로 LLM 강화학습 학습 노트북 생성  
  - 사용자 프롬프트: 정책 모델, 보상 모델, KL divergence 페널티, PPO, GRPO 등 핵심 개념을 다루는 노트북을 만들고, 각 셀에서 동작 원리를 설명할 것  
  - 작은 어휘·GRU 기반의 **소형 토이 모델**을 사용해 API 키 없이 CPU에서 전체 실행 가능하도록 구성  
  
- ## Example 2: Codex로 노트북의 다중 버그 수정  
  - 사용자 프롬프트: 2023년 이후 갱신되지 않은 `churn_analysis.ipynb`를 끝까지 깔끔히 실행되도록 수정, 실패 셀 각각을 식별·수정·검증하고, 변경 셀 위에 무엇이 어떻게 문제였는지 마크다운 노트 추가  
  - Codex가 수정한 4가지 버그  
    - 하드코딩된 파일 경로  
    - **pandas 2.0에서 제거된** `DataFrame.append()`  
    - sklearn 0.20에서 제거된 `sklearn.cross_validation`  
    - sklearn 1.2에서 제거된 `plot_confusion_matrix`  
  - 수정 후 노트북이 엔드 투 엔드로 정상 실행됨을 검증  
  
### 시작하기  
  
- 설치 스크립트, `cargo install nb-cli`, 소스 빌드(`cargo build --release`) 세 가지 설치 경로 제공  
- 빌드 시 바이너리는 `target/release/nb`에 생성  
- AI 에이전트가 모든 노트북 작업에 nb를 쓰도록 하려면 **스킬 설치 명령** `npx skills install jupyter-ai-contrib/nb-cli` 지원  
  
### 개발자 및 참여  
  
- AWS 소속의 Jupyter 프로젝트 기여자 3인이 개발에 참여  
  - Andrii Ieroshenko: AWS Software Development Engineer, JupyterLab·Jupyter AI 등 장기 기여자, Jupyter Media Strategy Working Group 멤버  
  - Brian Granger: AWS Senior Principal Technologist, **Project Jupyter 공동 창립자**, Jupyter·PyTorch Foundation 보드 멤버  
  - Piyush Jain: AWS Principal Engineer, Jupyter·Agentic AI 담당, Jupyter Server Council 멤버  
- nb-cli는 초기 단계로, 설치·사용 후 GitHub 이슈 등록, `jupyter-ai-contrib` 디스커션 참여, 버그 리포트·기능 요청·PR을 통한 기여를 요청

## Comments



### Comment 58253

- Author: jessyt
- Created: 2026-05-26T11:35:43+09:00
- Points: 1

사례 위주로 작성해주셔서 참고할게 많네요!