███╗   ██╗ ██████╗ ████████╗██╗ ██████╗ ███╗   ██╗     ██████╗██╗     ██╗
████╗  ██║██╔═══██╗╚══██╔══╝██║██╔═══██╗████╗  ██║    ██╔════╝██║     ██║
██╔██╗ ██║██║   ██║   ██║   ██║██║   ██║██╔██╗ ██║    ██║     ██║     ██║
██║╚██╗██║██║   ██║   ██║   ██║██║   ██║██║╚██╗██║    ██║     ██║     ██║
██║ ╚████║╚██████╔╝   ██║   ██║╚██████╔╝██║ ╚████║    ╚██████╗███████╗██║
╚═╝  ╚═══╝ ╚═════╝    ╚═╝   ╚═╝ ╚═════╝ ╚═╝  ╚═══╝     ╚═════╝╚══════╝╚═╝

중요 고지:

이 프로젝트는 Notion API를 활용하는 독립적인 비공식 CLI 도구입니다. Notion Labs, Inc.와 제휴, 보증, 후원 관계가 없습니다. "Notion"은 Notion Labs, Inc.의 등록 상표입니다.

AI 에이전트 & 자동화를 위한 Notion CLI (v5.9.0 · 5단계 성능 최적화)

프로젝트 소개

Notion API를 위한 강력한 CLI 도구로, AI 코딩 어시스턴트와 자동화 스크립트에 최적화되어 있습니다.

주요 기능:

• 빠른 네이티브 API 통합 — 인텔리전트 캐싱으로 최대 100배 빠른 반복 읽기
• AI 우선 설계 — JSON 출력 모드, 구조화된 에러, 표준 종료 코드
• 비대화형 — 스크립트 및 자동화에 완벽히 적합
• 유연한 출력 — JSON, Markdown, Pretty, Compact JSON, Raw API 응답
• 최신 API — Notion API v5.2.1, data sources 완전 지원
• 향상된 안정성 — 지수 백오프 자동 재시도 + 서킷 브레이커
• 5단계 성능 최적화 — 배치 작업 1.5-2배 성능 향상 (v5.9.0)
• 스키마 탐색 — AI 친화적 데이터베이스 스키마 추출
• 워크스페이스 캐싱 — API 호출 없이 빠른 데이터베이스 조회
• 스마트 ID 변환 — database_id ↔ data_source_id 자동 변환
• 보안 — 운영 취약점 0건

---

📦 설치 & 설정

# npm 설치 (권장)
npm install -g @infograb/notion-cli

# 최신 버전으로 업데이트
npm update -g @infograb/notion-cli

최초 설정:

# 대화형 설정 마법사 실행
notion-cli init

init 명령어가 다음을 안내합니다: API 토큰 설정 → 연결 테스트 → 워크스페이스 동기화

수동 설정:

export NOTION_TOKEN="secret_your_token_here"
notion-cli whoami   # 연결 확인
notion-cli sync     # 워크스페이스 캐시 동기화

토큰 발급: https://developers.notion.com/docs/create-a-notion-integration

---

🔑 핵심 기능

Simple Properties — 복잡도 70% 감소

-S 플래그로 플랫 JSON을 사용해 페이지를 생성·수정합니다:

# 기존 방식 (중첩 구조)
notion-cli page create -d DB_ID --properties '{"Name": {"title": [{"text": {"content": "Task"}}]}, "Status": {"select": {"name": "Done"}}}'

# Simple Properties (-S 플래그)
notion-cli page create -d DB_ID -S --properties '{"Name": "Task", "Status": "Done", "Priority": 5, "Due Date": "tomorrow"}'

• 대소문자 구분 없음, 상대 날짜("today", "+7 days") 지원
• 13가지 속성 타입: title, rich_text, number, checkbox, select, multi_select, status, date, url, email, phone, people, relation

Smart ID Resolution — 자동 ID 변환

# database_id와 data_source_id 모두 사용 가능
notion-cli db retrieve 1fb79d4c71bb8032b722c82305b63a00  # database_id
notion-cli db retrieve 2gc80e5d82cc9043c833d93416c74b11  # data_source_id

JSON Mode — AI 처리 최적화

notion-cli db query <ID> --json | jq '.data.results[].properties'
# 에러도 JSON 반환: {"success": false, "error": {"code": "NOT_FOUND", ...}}

종료 코드: 0 = 성공, 1 = API 오류, 2 = CLI 오류

Schema Discovery — 스키마 탐색

notion-cli db schema <DATA_SOURCE_ID> --json            # 전체 스키마
notion-cli db schema <ID> --with-examples --json        # 복사 가능한 예시 포함
notion-cli db schema <ID> --properties Status,Priority  # 특정 속성만

Workspace Caching — 워크스페이스 캐싱

notion-cli sync                           # 전체 워크스페이스 캐시 (1회)
notion-cli db query "Tasks Database"      # 이름으로 조회 (API 호출 없음)
notion-cli cache:info --json              # 캐시 상태 확인

---

📋 주요 명령어

설정 & 진단

명령어	설명
notion-cli init	대화형 최초 설정 마법사
notion-cli doctor	7가지 헬스 체크 진단
notion-cli whoami	연결 및 봇 정보 확인
notion-cli config set-token	API 토큰 설정

데이터베이스

notion-cli db retrieve <ID>                                # 메타데이터 조회
notion-cli db query <ID> --json                            # 쿼리
notion-cli db schema <ID> --json                           # 스키마 추출
notion-cli db update <ID> --title "New Title"              # 업데이트
notion-cli db create --parent-page <PAGE_ID> --title "DB"  # 생성

페이지

notion-cli page create -d <ID> -S --properties '{"Name": "Task"}'    # 생성
notion-cli page retrieve <PAGE_ID> --json                              # 조회
notion-cli page update <PAGE_ID> -S --properties '{"Status": "Done"}' # 수정

블록

notion-cli block retrieve <BLOCK_ID>                   # 블록 조회
notion-cli block append <BLOCK_ID> --children '[...]'  # 자식 추가
notion-cli block update <BLOCK_ID> --content "텍스트"  # 수정

사용자 & 검색

notion-cli user list --json               # 전체 사용자 목록
notion-cli user retrieve <USER_ID>        # 사용자 조회
notion-cli search "project" --json        # 워크스페이스 검색
notion-cli search "docs" --filter page    # 페이지로 필터링

워크스페이스

notion-cli sync          # 워크스페이스 동기화
notion-cli list --json   # 캐시된 데이터베이스 목록

---

🔍 데이터베이스 필터링

# 단일 조건
notion-cli db query <ID> --filter '{"property": "Status", "select": {"equals": "Done"}}' --json

# 복합 조건 (AND)
notion-cli db query <ID> \
  --filter '{"and": [{"property": "Status", "select": {"equals": "Done"}}, {"property": "Priority", "number": {"greater_than": 5}}]}' \
  --json

# 텍스트 검색
notion-cli db query <ID> --search "urgent" --json

# 파일에서 필터 로드
notion-cli db query <ID> --file-filter ./filter.json --json

자세한 내용: docs/FILTER_GUIDE.md

---

📊 출력 형식

플래그	설명
--json	구조화된 JSON ({success, data, metadata})
--compact-json	한 줄 압축 JSON
--markdown	Markdown 테이블
--pretty	테두리 있는 테이블
--raw	원시 API 응답

---

⚙️ 환경 변수

변수	기본값	설명
NOTION_TOKEN	—	Notion API 토큰 (필수)
NOTION_RETRY_MAX_ATTEMPTS	3	최대 재시도 횟수
NOTION_RETRY_INITIAL_DELAY	1000	초기 지연 (ms)
NOTION_RETRY_MAX_DELAY	30000	최대 지연 (ms)
NOTION_CB_FAILURE_THRESHOLD	5	서킷 브레이커 임계값
NOTION_CACHE_DISABLED	false	전체 캐싱 비활성화
NOTION_CLI_VERBOSE	false	stderr에 구조화 이벤트 로깅
NOTION_CLI_DEDUP_ENABLED	true	요청 중복 제거
NOTION_CLI_DELETE_CONCURRENCY	5	병렬 블록 삭제 수
NOTION_CLI_CHILDREN_CONCURRENCY	10	병렬 자식 페치 수
NOTION_CLI_DISK_CACHE_ENABLED	true	디스크 캐시 활성화
NOTION_CLI_DISK_CACHE_MAX_SIZE	104857600	최대 캐시 크기 (100MB)
NOTION_CLI_HTTP_KEEP_ALIVE	true	HTTP Keep-Alive
DEBUG	—	notion-cli:* 로 디버그 로깅

---

🚀 성능 최적화 (v5.9.0)

배치 작업과 반복 데이터 접근에서 전체 1.5-2배 성능 향상.

최적화	최대 효과	일반 효과	적용 시나리오
요청 중복 제거	50% API 호출 감소	5-15% 감소	동시 중복 요청
병렬 작업	80% 빠름	60-70% 빠름	배치 삭제, 대량 조회
디스크 캐시	60% 히트율 향상	20-30% 향상	반복 CLI 세션
HTTP Keep-Alive	20% 빠름	5-10% 빠름	다중 요청 작업
응답 압축	70% 대역폭 절감	가변	대용량 JSON 응답

모든 최적화는 환경 변수로 독립 제어 가능하며, 하위 호환성 완전 유지.

---

🛠 개발 & 기여

요구 사항: Node.js >= 22.0.0, npm >= 8.0.0

# 저장소 클론 및 설치
git clone https://github.com/infograb/notion-cli
cd notion-cli && npm install && npm run build

# 개발 명령어
npm test              # 테스트 실행
npm run lint          # 린트 검사
npm run lint -- --fix # 자동 수정
npm link              # 전역 로컬 테스트

기술 스택: TypeScript · ESLint v9 · Prettier · Mocha + Chai

기여: Fork → 기능 브랜치 → 테스트 추가 → Pull Request

자세한 내용: CONTRIBUTING.md | docs/

---

📄 라이선스 & 법적 고지

• 라이선스: MIT — LICENSE 참고
• 상표: "Notion"은 Notion Labs, Inc.의 등록 상표로, 이 프로젝트는 Notion Labs, Inc.와 무관한 독립 도구입니다.
• 서드파티: NOTICE 파일에서 전체 오픈소스 라이선스 정보 확인

---

문의: oss@infograb.net · GitHub Issues · npm