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

• 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을 통한 기여를 요청

댓글과 토론