GitHub - infograb/notion-cli: Enterprise-grade Notion CLI for AI agents and automation. Non-interactive, structured output, advanced retry/caching. Notion API v5.2.1 with data sources support.

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

중요 고지:

이 프로젝트는 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

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.github		.github
bin		bin
dist		dist
docs		docs
examples/filters		examples/filters
scripts		scripts
src		src
test		test
.codecov.yml		.codecov.yml
.env.example		.env.example
.gitignore		.gitignore
.mocharc.json		.mocharc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package-lock.json.backup		package-lock.json.backup
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

프로젝트 소개

📦 설치 & 설정

🔑 핵심 기능

Simple Properties — 복잡도 70% 감소

Smart ID Resolution — 자동 ID 변환

JSON Mode — AI 처리 최적화

Schema Discovery — 스키마 탐색

Workspace Caching — 워크스페이스 캐싱

📋 주요 명령어

설정 & 진단

데이터베이스

페이지

블록

사용자 & 검색

워크스페이스

🔍 데이터베이스 필터링

📊 출력 형식

⚙️ 환경 변수

🚀 성능 최적화 (v5.9.0)

🛠 개발 & 기여

📄 라이선스 & 법적 고지

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

프로젝트 소개

📦 설치 & 설정

🔑 핵심 기능

Simple Properties — 복잡도 70% 감소

Smart ID Resolution — 자동 ID 변환

JSON Mode — AI 처리 최적화

Schema Discovery — 스키마 탐색

Workspace Caching — 워크스페이스 캐싱

📋 주요 명령어

설정 & 진단

데이터베이스

페이지

블록

사용자 & 검색

워크스페이스

🔍 데이터베이스 필터링

📊 출력 형식

⚙️ 환경 변수

🚀 성능 최적화 (v5.9.0)

🛠 개발 & 기여

📄 라이선스 & 법적 고지

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages