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

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

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

AI 코딩 에이전트가 Jupyter 노트북을 아티팩트로 다룰 수 있도록 설계된 실험적 오픈소스 CLI 도구 появился. Rust 기반으로 구현되어 빠르고 안정적인 노트북 조작을 지원하는 이 도구는 .ipynb JSON 구조가 자동화와 LLM 처리에 적합하지 않다는 문제를 해결한다. nbformat 사양을 따르면서도 읽기·쓰기·실행·검색 기능을 명령줄로 제공하며, Jupyter 서버 없이도 동작하는 것이 특징이다.

---

왜 nb-cli가 필요한가

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 서버 유무에 관계없이 동작

nb-cli의 가장 큰 장점 중 하나는 Jupyter 서버 없이도 동작한다는 것이다. 기본적으로 .ipynb 파일을 직접 읽고 쓰며, ZeroMQ를 통해 커널과 직접 통신해 실행한다. 서버 실행이 불필요한 스크립트와 CI 파이프라인에 적합하다.

nb create analysis.ipynbnb cell add analysis.ipynbnb execute analysis.ipynbnb read analysis.ipynb

여러 사용자나 에이전트가 동시에 같은 노트북을 편집할 때는 서버 연결이 유용하다. JupyterLab이 내부적으로 사용하는 것과 같은 Y.js CRDT 프로토콜로 충돌 없는 실시간 동기화를 제공한다. nb connect로 로컬 서버를 자동 감지하고, --server 옵션으로 특정 서버와 토큰을 지정할 수 있다. --restart-kernel 옵션으로 재현성 점검을 위한 커널 재시작도 지원한다.

서버 연결 시 JupyterLab에서 노트북이 열려 있는지 감지하고, 열려 있지 않으면 파일 기반 동작으로 자연스럽게 폴백한다.

AI 최적화 마크다운 포맷

언어 모델은 JSON을 파싱하지 않고 토큰을 예측하므로, 깊게 중첩된 Jupyter JSON은 컨텍스트 윈도우에서 비효율적이다. Jupyter 기본 포맷은 소스가 문자열 배열, 출력이 base64 블롭, 메타데이터가 다층 중첩으로 구성되어 있어 LLM 입장에서 토큰의 30~40%가 중괄호·대괄호·이스케이프 같은 구조 문자로 의미 없이 소모된다.

일반 Markdown은 토큰 효율은 좋지만 모호함이 크다. #이 마크다운 헤딩인지 Python 주석인지 구분할 수 없고, 코드 펜스가 노트북 셀인지 문서 내 예시인지 구분할 수 없다. "7번 셀의 오류를 고쳐줘"라고 했을 때 셀 위치를 안정적으로 식별할 구조적 마커도 부재하다.

nb-cli는 이를 해결하기 위해 라인 단위 센티넬 포맷을 설계했다. @@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은 셀이 이동해도 변하지 않는 안정 ID를 제공한다. 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-errorsnb search analysis.ipynb "KeyError" --scope outputnb search analysis.ipynb "TODO" --cell-type markdown

에이전트는 --with-errors로 실패 셀만 받아 처리하고, --scope output과 결합해 에러 트레이스백을 직접 검색할 수 있다. 사람도 deprecated API 감사, 대형 노트북에서의 함수 위치 파악, 리팩터 전 패턴 추출에 활용할 수 있다.

다중 셀 일괄 조작

마크다운 헤더 → 설정 코드 → 분석 같은 셀 시퀀스 추가가 흔한 패턴이다. 셀 하나씩 추가하면 왕복 횟수와 인덱스 관리 부담이 증가한다. 센티넬 포맷으로 한 호출에 여러 셀 추가를 지원한다.

printf '@@markdown\n## Summary\n\n@@code\ndf.describe()\n' | nb cell add report.ipynb --source -

@@cell {"cell_type": "..."} 형태의 전체 JSON 포맷도 지원한다. 동일한 일괄 처리 철학이 실행과 삭제에도 적용된다. nb execute analysis.ipynb --start 2 --end 5로 범위 실행하고, nb cell delete analysis.ipynb --range 0:3으로 범위 삭제가 가능하다.

환경 인식 실행

nb connect, nb execute, nb create에서 --uv, --pixi 플래그를 지원해 해당 환경 매니저로 Jupyter 서버와 커널을 탐색한다. nb status --python은 연결된 커널과 동일 환경에서 Python을 실행할 명령 프리픽스를 반환한다.

$(nb status --python) python -c "..."

---

실제 사용 사례

AI 에이전트 워크플로우

실패 셀 탐색 → 코드 수정 → 재실행을 명령으로 연결해 분석 워크플로우의 일부로 노트북 조작이 가능하다.

nb search data_analysis.ipynb --with-errorsnb 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-errorsnb search analysis.ipynb "pandas.np"  # deprecated API 사용 탐색nb search notebook.ipynb "eval("     # 보안 우려 패턴 탐색nb read failing_notebook.ipynb --cell-index 5nb 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는 AI 에이전트와 Jupyter 노트북 사이의 격차를 해소하는 도구다. Rust 기반의 빠르고 안정적인 성능, Jupyter 서버 없는 독립 동작, 센티넬 기반 AI 최적화 마크다운 포맷, Unix 조합성, 강력한 검색과 다중 셀 일괄 조작, 환경 인식 실행 등의 기능을 제공한다. AI 코딩 에이전트를 활용한북 워크플로우를 자동화하고자 하는 개발자에게 유용하다. nb-cli는 현재 초기 단계로, 설치와 사용 후 GitHub 이슈 등록과 버그 리포트·기능 요청·PR을 통한 기여를 요청하고 있다.

---

📚 출처

• nb-cli: A Command-Line Interface for AI Agents and Notebook Automation

• GitHub - jupyter-ai-contrib/nb-cli

---

📚 출처

• https://news.hada.io/topic?id=29871