명령¶

nl에는 아홉 명령이 있습니다. 각 절은 «무엇을 바꾸는가», «실패하면 어떻게 되는가»를 적습니다.

최소 예제¶

nl diff notes/topic/3장_08.md          # 변경 목록과 번호
nl add  notes/topic/3장_08.md#1,3      # 반영할 변경 선택
nl push --apply                        # 실제 반영

push는 --apply가 없으면 아무것도 쓰지 않고 계획만 출력합니다.

nl diff <노트> [--page <id>] [--json]

로컬 파일과 노션 페이지를 비교하고 변경에 [1]부터 번호를 붙입니다. 비교 결과는 records/diffs/에 남습니다. 파일은 바꾸지 않습니다.

출력 표시	뜻
`patch`	글자나 서식이 다름
`insert`	로컬에만 있음(반영하면 추가됨)
`원격 전용`	노션에만 있음(기본은 그대로 둠, `--prune`일 때만 삭제)
`<원격 우선>`	마지막에 사람이 노션에서 고침
`<충돌>`	로컬과 원격이 모두 고침
`note representation_diff`	종류만 다르고 내용이 같은 자리(그림 자리표시자 등). 쓰지 않음

원격 우선이나 충돌이 있으면 종료 코드 3입니다.

nl add <노트>            # 파일 전체
nl add <노트>#1,3        # 번호로 선택
nl add <노트>#1 --delete # 원격 전용 블록 삭제 후보까지 선택

선택 결과는 records/stage/<노트>.json에 저장됩니다. diff 지문도 함께 저장하므로, 그 사이 파일이 바뀌면 push가 중단합니다.

원격 우선·충돌 블록은 고를 수 없습니다. 먼저 pull이나 keep으로 결정해야 합니다.

nl push [<노트>] [--apply] [--prune] [--force] [--json]

무대에 오른 변경만 노션에 씁니다. 노트를 생략하면 무대 전체를 처리합니다.

옵션	동작
`--apply`	실제로 씀. 없으면 미리보기
`--prune`	원격 전용 블록 삭제. 댓글이 없을 때만
`--force`	원격 우선·충돌까지 로컬로 덮어씀. 무대를 무시하고 계획 전체를 씀

쓰기 순서는 잠금 → 스냅숏 → 저널(planned) → 블록별 적용 → 재조회 검증 → base 갱신입니다. 검증이 실패하면 스냅숏 경로를 출력합니다.

nl pull <노트>          # 원격에서 바뀐 블록 목록
nl pull <노트>#2        # 2번 블록의 원격 내용을 로컬 파일로

원격 내용을 로컬 마크다운에 씁니다. 원격이 이깁니다. 적용한 뒤 base를 갱신합니다.

nl keep <노트>#2

로컬 수정을 유지하겠다고 표시합니다. base를 «현재 원격 값»으로 갱신해 덮어쓰기를 승인합니다. 이후 diff에서 그 블록은 local_ahead가 되어 push할 수 있습니다.

keep은 되돌릴 수 있는 작업이 아닙니다. 원격 내용은 사라집니다.

nl merge <노트>

원격 우선·충돌 블록을 나열하고 해소 방법을 안내합니다. 선택 자체는 pull과 keep이 합니다. 충돌이 있으면 종료 코드 3입니다.

nl rebase <노트>

원격만 바뀐 블록을 로컬 파일에 먼저 반영합니다. 충돌 블록은 로컬 값을 그대로 두고 목록으로 남깁니다. 충돌이 있으면 종료 코드 3입니다.

nl auth status [notion|google|all]
nl auth login  [notion|google|all]
nl auth logout [notion|google|all]

토큰 상태를 확인하고 저장·삭제합니다. 토큰 값은 출력하지 않습니다.

nl config

저장소 경로, 설정값과 그 출처(파일·환경 변수·기본값)를 JSON으로 출력합니다.

python -m notionml.core lint <노트>     # 정적 검사(모양·지문·타입·스타일)

roundtrip은 테스트 전용 함수이며 명령줄에 없습니다.